@etus/ui 0.1.0 → 0.1.2

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

@@ -1,787 +0,0 @@
-# Form
-
-## Visão Geral
-
-### Proposito
-
-O componente **Form** fornece uma integracao completa entre React Hook Form e componentes de UI, oferecendo gerenciamento de estado de formulario, validacao, e acessibilidade de forma declarativa e type-safe.
-
-### Quando Usar
-
-| Cenario | Recomendado |
-|---------|-------------|
-| Formularios com validacao complexa | Sim |
-| Multiplos campos interdependentes | Sim |
-| Feedback de erro em tempo real | Sim |
-| Formularios com estado controlado | Sim |
-| Input unico sem validacao | Nao (use inputs diretos) |
-| Formularios extremamente simples | Opcional |
-
-### Composicao
-
-O sistema Form segue o padrao **Compound Component**:
-
-```
-Form (Provider)
-  FormField (Controller)
-    FormItem (Container)
-      FormLabel
-      FormControl
-      FormDescription
-      FormMessage
-```
-
----
-
-## Design Specs
-
-### Tokens de Design
-
-| Token | Valor | Uso |
-|-------|-------|-----|
-| `--spacing-gap` | `0.5rem` (8px) | Espaco entre elementos do FormItem |
-| `--color-destructive` | OKLCH | Cor de erro (label e mensagem) |
-| `--color-muted-foreground` | OKLCH | Cor da descricao |
-| `--font-size-sm` | `0.875rem` | Tamanho de descricao e mensagem |
-
-### Estados Visuais
-
-| Estado | Indicador Visual |
-|--------|------------------|
-| Default | Label com cor padrao |
-| Error | Label e mensagem em `text-destructive` |
-| Disabled | Opacidade reduzida (via input) |
-| Focus | Controlado pelo input filho |
-
-### Atributos Data
-
-| Atributo | Componente | Valores |
-|----------|------------|---------|
-| `data-slot="form-item"` | FormItem | - |
-| `data-slot="form-label"` | FormLabel | - |
-| `data-slot="form-control"` | FormControl | - |
-| `data-slot="form-description"` | FormDescription | - |
-| `data-slot="form-message"` | FormMessage | - |
-| `data-error` | FormLabel | `true` / `false` |
-
----
-
-## API
-
-### Form
-
-Re-exporta `FormProvider` do React Hook Form.
-
-```typescript
-import { useForm } from "react-hook-form"
-import { Form } from "@etus/ui"
-
-const form = useForm<FormValues>()
-
-<Form {...form}>
-  {/* campos */}
-</Form>
-```
-
-### FormField
-
-Wrapper do `Controller` que fornece contexto do campo.
-
-```typescript
-interface FormFieldProps<
-  TFieldValues extends FieldValues = FieldValues,
-  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>
-> extends ControllerProps<TFieldValues, TName> {}
-```
-
-| Prop | Tipo | Obrigatorio | Descricao |
-|------|------|-------------|-----------|
-| `name` | `FieldPath<TFieldValues>` | Sim | Nome do campo no formulario |
-| `control` | `Control<TFieldValues>` | Nao | Control do useForm (inferido do contexto) |
-| `render` | `({ field, fieldState, formState }) => ReactNode` | Sim | Funcao de renderizacao |
-| `rules` | `RegisterOptions` | Nao | Regras de validacao |
-| `defaultValue` | `TFieldValues[TName]` | Nao | Valor padrao |
-
-### FormItem
-
-Container que agrupa label, controle, descricao e mensagem.
-
-```typescript
-interface FormItemProps extends React.ComponentProps<"div"> {}
-```
-
-| Prop | Tipo | Padrao | Descricao |
-|------|------|--------|-----------|
-| `className` | `string` | - | Classes CSS adicionais |
-| `children` | `ReactNode` | - | Componentes filhos |
-
-### FormLabel
-
-Label acessivel vinculado ao controle.
-
-```typescript
-interface FormLabelProps extends React.ComponentProps<typeof LabelPrimitive.Root> {}
-```
-
-| Prop | Tipo | Padrao | Descricao |
-|------|------|--------|-----------|
-| `className` | `string` | - | Classes CSS adicionais |
-| `children` | `ReactNode` | - | Texto do label |
-
-**Comportamento automatico:**
-- `htmlFor` vinculado ao FormControl
-- Estilo de erro quando campo invalido
-
-### FormControl
-
-Slot que injeta props de acessibilidade no input filho.
-
-```typescript
-interface FormControlProps extends React.ComponentProps<typeof Slot> {}
-```
-
-**Props injetadas automaticamente:**
-- `id`: ID unico do campo
-- `aria-describedby`: IDs de descricao e mensagem de erro
-- `aria-invalid`: `true` quando ha erro
-
-### FormDescription
-
-Texto de ajuda para o campo.
-
-```typescript
-interface FormDescriptionProps extends React.ComponentProps<"p"> {}
-```
-
-### FormMessage
-
-Exibe mensagem de erro do campo.
-
-```typescript
-interface FormMessageProps extends React.ComponentProps<"p"> {}
-```
-
-**Comportamento:**
-- Renderiza mensagem de erro quando existe
-- Pode receber `children` para mensagem customizada
-- Retorna `null` quando nao ha erro
-
-### useFormField
-
-Hook para acessar estado do campo dentro do FormItem.
-
-```typescript
-function useFormField(): {
-  id: string
-  name: string
-  formItemId: string
-  formDescriptionId: string
-  formMessageId: string
-  invalid: boolean
-  isDirty: boolean
-  isTouched: boolean
-  isValidating: boolean
-  error?: FieldError
-}
-```
-
----
-
-## Acessibilidade (A11y)
-
-### Conformidade WCAG 2.1 AA
-
-| Criterio | Status | Implementacao |
-|----------|--------|---------------|
-| 1.3.1 Info and Relationships | Cumprido | Labels vinculados via `htmlFor` |
-| 1.3.5 Identify Input Purpose | Cumprido | `autocomplete` suportado via input |
-| 3.3.1 Error Identification | Cumprido | `aria-invalid` + mensagem de erro |
-| 3.3.2 Labels or Instructions | Cumprido | FormLabel + FormDescription |
-| 4.1.2 Name, Role, Value | Cumprido | Semantica HTML nativa |
-
-### Atributos ARIA
-
-```tsx
-// Gerado automaticamente pelo FormControl
-<input
-  id="form-item-123"
-  aria-describedby="form-item-123-description form-item-123-message"
-  aria-invalid="true" // quando ha erro
-/>
-```
-
-### Navegacao por Teclado
-
-| Tecla | Acao |
-|-------|------|
-| `Tab` | Navega entre campos |
-| `Shift + Tab` | Navega para campo anterior |
-| `Enter` | Submete formulario (em inputs de texto) |
-| `Space` | Ativa checkboxes/radio buttons |
-
-### Anuncio de Erros
-
-O FormMessage usa `aria-describedby` para que leitores de tela anunciem erros automaticamente quando o campo recebe foco.
-
----
-
-## Exemplos
-
-### Formulario Basico
-
-```tsx
-import { useForm } from "react-hook-form"
-import { zodResolver } from "@hookform/resolvers/zod"
-import { z } from "zod"
-import {
-  Form,
-  FormField,
-  FormItem,
-  FormLabel,
-  FormControl,
-  FormDescription,
-  FormMessage,
-} from "@etus/ui"
-import { TextInput } from "@etus/ui"
-import { Button } from "@etus/ui"
-
-const formSchema = z.object({
-  username: z.string().min(2, "Username deve ter pelo menos 2 caracteres"),
-  email: z.string().email("Email invalido"),
-})
-
-type FormValues = z.infer<typeof formSchema>
-
-export function SignupForm() {
-  const form = useForm<FormValues>({
-    resolver: zodResolver(formSchema),
-    defaultValues: {
-      username: "",
-      email: "",
-    },
-  })
-
-  function onSubmit(values: FormValues) {
-    console.log(values)
-  }
-
-  return (
-    <Form {...form}>
-      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
-        <FormField
-          control={form.control}
-          name="username"
-          render={({ field }) => (
-            <FormItem>
-              <FormLabel>Username</FormLabel>
-              <FormControl>
-                <TextInput placeholder="seu-username" {...field} />
-              </FormControl>
-              <FormDescription>
-                Seu nome de usuario publico.
-              </FormDescription>
-              <FormMessage />
-            </FormItem>
-          )}
-        />
-
-        <FormField
-          control={form.control}
-          name="email"
-          render={({ field }) => (
-            <FormItem>
-              <FormLabel>Email</FormLabel>
-              <FormControl>
-                <TextInput type="email" placeholder="voce@exemplo.com" {...field} />
-              </FormControl>
-              <FormMessage />
-            </FormItem>
-          )}
-        />
-
-        <Button type="submit">Cadastrar</Button>
-      </form>
-    </Form>
-  )
-}
-```
-
-### Formulario com Select
-
-```tsx
-import {
-  Form,
-  FormField,
-  FormItem,
-  FormLabel,
-  FormControl,
-  FormMessage,
-} from "@etus/ui"
-import {
-  Select,
-  SelectContent,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-} from "@etus/ui"
-
-<FormField
-  control={form.control}
-  name="role"
-  render={({ field }) => (
-    <FormItem>
-      <FormLabel>Funcao</FormLabel>
-      <Select onValueChange={field.onChange} defaultValue={field.value}>
-        <FormControl>
-          <SelectTrigger>
-            <SelectValue placeholder="Selecione uma funcao" />
-          </SelectTrigger>
-        </FormControl>
-        <SelectContent>
-          <SelectItem value="admin">Administrador</SelectItem>
-          <SelectItem value="editor">Editor</SelectItem>
-          <SelectItem value="viewer">Visualizador</SelectItem>
-        </SelectContent>
-      </Select>
-      <FormMessage />
-    </FormItem>
-  )}
-/>
-```
-
-### Formulario com Checkbox
-
-```tsx
-import { Checkbox } from "@etus/ui"
-
-<FormField
-  control={form.control}
-  name="terms"
-  render={({ field }) => (
-    <FormItem className="flex flex-row items-start space-x-3 space-y-0">
-      <FormControl>
-        <Checkbox
-          checked={field.value}
-          onCheckedChange={field.onChange}
-        />
-      </FormControl>
-      <div className="space-y-1 leading-none">
-        <FormLabel>Aceitar termos e condicoes</FormLabel>
-        <FormDescription>
-          Voce concorda com nossos Termos de Servico e Politica de Privacidade.
-        </FormDescription>
-      </div>
-    </FormItem>
-  )}
-/>
-```
-
-### Formulario com Validacao Async
-
-```tsx
-const formSchema = z.object({
-  username: z.string()
-    .min(2)
-    .refine(async (username) => {
-      const exists = await checkUsernameExists(username)
-      return !exists
-    }, "Username ja esta em uso"),
-})
-
-// O FormMessage exibira o erro de validacao async automaticamente
-```
-
-### Layout Horizontal com Field
-
-```tsx
-import { Field, FieldLabel, FieldDescription, FieldError } from "@etus/ui"
-
-<FormField
-  control={form.control}
-  name="notifications"
-  render={({ field, fieldState }) => (
-    <Field orientation="horizontal">
-      <FormControl>
-        <Switch
-          checked={field.value}
-          onCheckedChange={field.onChange}
-        />
-      </FormControl>
-      <FieldLabel>
-        <FieldTitle>Notificacoes por email</FieldTitle>
-        <FieldDescription>
-          Receba atualizacoes sobre sua conta.
-        </FieldDescription>
-        {fieldState.error && (
-          <FieldError>{fieldState.error.message}</FieldError>
-        )}
-      </FieldLabel>
-    </Field>
-  )}
-/>
-```
-
----
-
-## Testes
-
-### Configuracao
-
-```typescript
-import { render, screen } from "@testing-library/react"
-import userEvent from "@testing-library/user-event"
-import { axe, toHaveNoViolations } from "jest-axe"
-import { useForm, FormProvider } from "react-hook-form"
-import {
-  Form,
-  FormField,
-  FormItem,
-  FormLabel,
-  FormControl,
-  FormMessage,
-} from "./Form"
-
-expect.extend(toHaveNoViolations)
-
-// Wrapper para testes
-function TestForm({
-  children,
-  defaultValues = {},
-}: {
-  children: React.ReactNode
-  defaultValues?: Record<string, unknown>
-}) {
-  const form = useForm({ defaultValues })
-  return <Form {...form}>{children}</Form>
-}
-```
-
-### Testes de Renderizacao
-
-```typescript
-describe("Form", () => {
-  it("renderiza FormItem com todos os slots", () => {
-    render(
-      <TestForm defaultValues={{ name: "" }}>
-        <FormField
-          name="name"
-          render={({ field }) => (
-            <FormItem>
-              <FormLabel>Nome</FormLabel>
-              <FormControl>
-                <input {...field} />
-              </FormControl>
-              <FormDescription>Seu nome completo</FormDescription>
-              <FormMessage />
-            </FormItem>
-          )}
-        />
-      </TestForm>
-    )
-
-    expect(screen.getByText("Nome")).toBeInTheDocument()
-    expect(screen.getByText("Seu nome completo")).toBeInTheDocument()
-    expect(screen.getByRole("textbox")).toBeInTheDocument()
-  })
-
-  it("vincula label ao input via htmlFor", () => {
-    render(
-      <TestForm defaultValues={{ email: "" }}>
-        <FormField
-          name="email"
-          render={({ field }) => (
-            <FormItem>
-              <FormLabel>Email</FormLabel>
-              <FormControl>
-                <input type="email" {...field} />
-              </FormControl>
-            </FormItem>
-          )}
-        />
-      </TestForm>
-    )
-
-    const label = screen.getByText("Email")
-    const input = screen.getByRole("textbox")
-    expect(label).toHaveAttribute("for", input.id)
-  })
-})
-```
-
-### Testes de Validacao
-
-```typescript
-describe("Form - Validacao", () => {
-  it("exibe mensagem de erro quando campo e invalido", async () => {
-    const user = userEvent.setup()
-
-    function FormWithValidation() {
-      const form = useForm({
-        defaultValues: { email: "" },
-        mode: "onBlur",
-      })
-
-      return (
-        <Form {...form}>
-          <form>
-            <FormField
-              name="email"
-              rules={{ required: "Email e obrigatorio" }}
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>Email</FormLabel>
-                  <FormControl>
-                    <input {...field} />
-                  </FormControl>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-          </form>
-        </Form>
-      )
-    }
-
-    render(<FormWithValidation />)
-
-    const input = screen.getByRole("textbox")
-    await user.click(input)
-    await user.tab()
-
-    expect(await screen.findByText("Email e obrigatorio")).toBeInTheDocument()
-  })
-
-  it("aplica estilo de erro no label", async () => {
-    const user = userEvent.setup()
-
-    function FormWithError() {
-      const form = useForm({
-        defaultValues: { name: "" },
-        mode: "onBlur",
-      })
-
-      return (
-        <Form {...form}>
-          <form>
-            <FormField
-              name="name"
-              rules={{ required: "Obrigatorio" }}
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>Nome</FormLabel>
-                  <FormControl>
-                    <input {...field} />
-                  </FormControl>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-          </form>
-        </Form>
-      )
-    }
-
-    render(<FormWithError />)
-
-    await user.click(screen.getByRole("textbox"))
-    await user.tab()
-
-    const label = screen.getByText("Nome")
-    expect(label).toHaveAttribute("data-error", "true")
-  })
-})
-```
-
-### Testes de Acessibilidade
-
-```typescript
-describe("Form - Acessibilidade", () => {
-  it("nao possui violacoes de acessibilidade", async () => {
-    const { container } = render(
-      <TestForm defaultValues={{ username: "" }}>
-        <FormField
-          name="username"
-          render={({ field }) => (
-            <FormItem>
-              <FormLabel>Username</FormLabel>
-              <FormControl>
-                <input {...field} />
-              </FormControl>
-              <FormDescription>Escolha um username unico</FormDescription>
-              <FormMessage />
-            </FormItem>
-          )}
-        />
-      </TestForm>
-    )
-
-    const results = await axe(container)
-    expect(results).toHaveNoViolations()
-  })
-
-  it("configura aria-describedby corretamente", () => {
-    render(
-      <TestForm defaultValues={{ bio: "" }}>
-        <FormField
-          name="bio"
-          render={({ field }) => (
-            <FormItem>
-              <FormLabel>Bio</FormLabel>
-              <FormControl>
-                <textarea {...field} />
-              </FormControl>
-              <FormDescription>Conte sobre voce</FormDescription>
-            </FormItem>
-          )}
-        />
-      </TestForm>
-    )
-
-    const textarea = screen.getByRole("textbox")
-    expect(textarea).toHaveAttribute("aria-describedby")
-    expect(textarea.getAttribute("aria-describedby")).toContain("description")
-  })
-
-  it("define aria-invalid quando campo tem erro", async () => {
-    const user = userEvent.setup()
-
-    function FormWithError() {
-      const form = useForm({
-        defaultValues: { field: "" },
-        mode: "onBlur",
-      })
-
-      return (
-        <Form {...form}>
-          <form>
-            <FormField
-              name="field"
-              rules={{ required: "Campo obrigatorio" }}
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>Campo</FormLabel>
-                  <FormControl>
-                    <input {...field} />
-                  </FormControl>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-          </form>
-        </Form>
-      )
-    }
-
-    render(<FormWithError />)
-
-    const input = screen.getByRole("textbox")
-    await user.click(input)
-    await user.tab()
-
-    expect(input).toHaveAttribute("aria-invalid", "true")
-  })
-})
-```
-
-### Testes de Data Attributes
-
-```typescript
-describe("Form - Data Slots", () => {
-  it("aplica data-slot em todos os componentes", () => {
-    const { container } = render(
-      <TestForm defaultValues={{ test: "" }}>
-        <FormField
-          name="test"
-          render={({ field }) => (
-            <FormItem>
-              <FormLabel>Test</FormLabel>
-              <FormControl>
-                <input {...field} />
-              </FormControl>
-              <FormDescription>Description</FormDescription>
-              <FormMessage>Error</FormMessage>
-            </FormItem>
-          )}
-        />
-      </TestForm>
-    )
-
-    expect(container.querySelector('[data-slot="form-item"]')).toBeInTheDocument()
-    expect(container.querySelector('[data-slot="form-label"]')).toBeInTheDocument()
-    expect(container.querySelector('[data-slot="form-control"]')).toBeInTheDocument()
-    expect(container.querySelector('[data-slot="form-description"]')).toBeInTheDocument()
-    expect(container.querySelector('[data-slot="form-message"]')).toBeInTheDocument()
-  })
-})
-```
-
----
-
-## Comparacao com Design Systems
-
-### Analise Comparativa
-
-| Feature | ETUS | Shadcn | Radix | React Aria | Chakra | MUI |
-|---------|------|--------|-------|------------|--------|-----|
-| React Hook Form | Nativo | Nativo | Manual | Manual | Plugin | Manual |
-| Validacao Zod | Sim | Sim | Manual | Manual | Sim | Manual |
-| Compound Components | Sim | Sim | Sim | Sim | Nao | Nao |
-| ARIA automatico | Sim | Sim | Sim | Sim | Parcial | Parcial |
-| TypeScript | Estrito | Estrito | Estrito | Estrito | Parcial | Parcial |
-| CSS-in-JS | Nao | Nao | Nao | Nao | Sim | Sim |
-
-### Recursos por Design System
-
-| Design System | Abordagem de Form | Pontos Fortes |
-|---------------|-------------------|---------------|
-| **Shadcn/ui** | Compound + RHF | Base do ETUS, integracao direta |
-| **Radix UI** | Primitivos baixo nivel | Flexibilidade maxima |
-| **React Aria** | Hooks + comportamento | Acessibilidade superior |
-| **Chakra UI** | Props declarativas | DX simples |
-| **MUI** | Componentes monoliticos | Ecossistema completo |
-| **Mantine** | Hook-based forms | useForm proprio |
-| **Ant Design** | Form.Item wrapper | Validacao integrada |
-| **NextUI** | Styled components | Visual moderno |
-| **Headless UI** | Comportamento puro | Zero estilos |
-| **Ariakit** | Composable hooks | Flexivel e acessivel |
-| **Fluent UI** | Enterprise-ready | Consistencia Microsoft |
-| **Carbon** | Design tokens IBM | Escalabilidade enterprise |
-| **Blueprint** | Data-dense UIs | Formularios complexos |
-| **PrimeReact** | Temas prontos | Produtividade rapida |
-
-### Diferenciais ETUS
-
-1. **Integracao nativa com React Hook Form** - Sem boilerplate adicional
-2. **Tipagem estrita** - FieldPath e FieldValues generics
-3. **Contexto automatico** - useFormField para acesso ao estado
-4. **ARIA automatico** - aria-describedby e aria-invalid gerenciados
-5. **Slots CSS** - data-slot para estilizacao precisa
-6. **Composabilidade** - Funciona com qualquer input
-
----
-
-## Dependencias
-
-```json
-{
-  "react-hook-form": "^7.x",
-  "@radix-ui/react-label": "^2.x",
-  "@radix-ui/react-slot": "^1.x"
-}
-```
-
-## Arquivos Relacionados
-
-- `Form.tsx` - Componente principal
-- `Field.tsx` - Componente Field complementar (layouts alternativos)
-- `Label.tsx` - Componente Label primitivo
-
----
-
-## Changelog
-
-| Versao | Data | Mudancas |
-|--------|------|----------|
-| 1.0.0 | 2024-01 | Lancamento inicial baseado no Shadcn/ui |
-| 1.1.0 | 2024-06 | Adicao de data-slot attributes |
-| 1.2.0 | 2024-12 | React 19 compatibility (ref as prop) |