@etus/ui 0.1.0

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

@@ -0,0 +1,905 @@
+# Textarea
+
+## Visão Geral
+
+O **Textarea** e um componente de entrada de texto multi-linha para o Design System ETUS, utilizado para capturar textos longos como descricoes, comentarios, mensagens e notas. Como elemento de formulario, integra-se com validacao, labels e mensagens de erro.
+
+### Casos de Uso
+
+- Campos de comentarios e feedback
+- Descricoes longas (produtos, projetos, tarefas)
+- Mensagens de contato e suporte
+- Notas e anotacoes em formularios
+- Campos de biografia ou sobre
+- Entrada de codigo ou texto formatado
+
+### Classificacao
+
+**Categoria:** Form Input
+**Dependencias:** Nenhuma dependencia externa (elemento nativo)
+
+---
+
+## Design Specs
+
+### Comportamento
+
+| Caracteristica | Valor | Descricao |
+|----------------|-------|-----------|
+| Auto-resize | `field-sizing-content` | Altura ajusta ao conteudo |
+| Min Height | `min-h-16` (64px) | Altura minima padrao |
+| Width | `w-full` | Ocupa 100% do container |
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Default | - | Borda `border-input`, fundo transparente |
+| Hover | Nativo | Nenhum estilo adicional |
+| Focus | `focus-visible:ring-[3px]` | Ring de 3px com `ring-ring/50`, borda `border-ring` |
+| Disabled | `disabled:opacity-50` | 50% opacidade, cursor not-allowed |
+| Invalid | `aria-invalid:ring-destructive/20` | Ring vermelho, borda `border-destructive` |
+| Placeholder | `placeholder:text-muted-foreground` | Texto placeholder com cor muted |
+
+### Dark Mode
+
+| Propriedade | Light Mode | Dark Mode |
+|-------------|------------|-----------|
+| Background | `transparent` | `bg-input/30` |
+| Invalid Ring | `ring-destructive/20` | `ring-destructive/40` |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--input              /* Cor da borda */
+--ring               /* Cor do focus ring */
+--destructive        /* Cor de erro */
+--muted-foreground   /* Cor do placeholder */
+
+/* Espacamento */
+px-3                 /* Padding horizontal */
+py-2                 /* Padding vertical */
+min-h-16             /* Altura minima (64px) */
+
+/* Tipografia */
+text-base            /* 16px mobile */
+md:text-sm           /* 14px desktop */
+
+/* Bordas */
+rounded-md           /* var(--radius) */
+border               /* 1px solid */
+
+/* Sombras */
+shadow-xs            /* Sombra sutil */
+
+/* Transicoes */
+transition-[color,box-shadow]  /* Animacao de foco */
+```
+
+### data-slot
+
+```html
+<textarea data-slot="textarea">...</textarea>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `value` | `string` | - | Valor controlado |
+| `defaultValue` | `string` | - | Valor inicial nao-controlado |
+| `placeholder` | `string` | - | Texto placeholder |
+| `rows` | `number` | - | Numero de linhas visiveis |
+| `cols` | `number` | - | Numero de colunas visiveis |
+| `maxLength` | `number` | - | Limite maximo de caracteres |
+| `minLength` | `number` | - | Minimo de caracteres requeridos |
+| `disabled` | `boolean` | `false` | Desabilita o componente |
+| `readOnly` | `boolean` | `false` | Somente leitura |
+| `required` | `boolean` | `false` | Campo obrigatorio |
+| `autoFocus` | `boolean` | `false` | Foco automatico ao montar |
+| `wrap` | `"soft" \| "hard" \| "off"` | `"soft"` | Comportamento de quebra de linha |
+| `className` | `string` | - | Classes CSS adicionais |
+| `ref` | `Ref<HTMLTextAreaElement>` | - | Referencia ao elemento DOM |
+
+> Herda todas as props de `React.ComponentProps<"textarea">`
+
+### Callbacks
+
+| Callback | Tipo | Descricao |
+|----------|------|-----------|
+| `onChange` | `(event: ChangeEvent<HTMLTextAreaElement>) => void` | Disparado ao alterar valor |
+| `onFocus` | `(event: FocusEvent<HTMLTextAreaElement>) => void` | Disparado ao receber foco |
+| `onBlur` | `(event: FocusEvent<HTMLTextAreaElement>) => void` | Disparado ao perder foco |
+| `onKeyDown` | `(event: KeyboardEvent<HTMLTextAreaElement>) => void` | Disparado ao pressionar tecla |
+| `onInput` | `(event: FormEvent<HTMLTextAreaElement>) => void` | Disparado a cada input |
+
+### TypeScript
+
+```typescript
+// Props do componente
+type TextareaProps = React.ComponentProps<"textarea">
+
+// Uso com ref (React 19)
+function MyComponent() {
+  const textareaRef = useRef<HTMLTextAreaElement>(null)
+
+  return <Textarea ref={textareaRef} />
+}
+```
+
+### Comparativo com Design Systems de Referencia
+
+#### Matriz de Features (14 Design Systems)
+
+| Feature | ETUS | Shadcn | Radix | React Aria | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon | Blueprint | PrimeReact |
+|---------|:----:|:------:|:-----:|:----------:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|:---------:|:----------:|
+| **Auto-resize** | `field-sizing` | `field-sizing` | - | - | `resize` prop | `maxRows` | `autosize` | `autoSize` | ✓ | - | - | `resize` | - | `growVertically` | `autoResize` |
+| **Variantes** | - | - | - | - | `variant` | `variant` | `variant` | `variant` | `variant` | - | - | `appearance` | - | - | - |
+| **Tamanhos** | - | - | - | - | `size` | `size` | `size` | `size` | `size` | - | - | `size` | - | - | - |
+| **Max/Min Rows** | - | - | - | - | - | ✓ | `minRows`/`maxRows` | `autoSize.minRows` | `minRows`/`maxRows` | - | - | - | - | ✓ | - |
+| **Character Count** | - | - | - | - | - | - | - | `showCount` | - | - | - | - | `enableCounter` | - | - |
+| **Clear Button** | - | - | - | - | - | - | - | `allowClear` | `isClearable` | - | - | - | - | - | - |
+| **data-slot** | ✓ | ✓ | - | - | - | - | - | - | ✓ | - | - | - | - | - | - |
+| **Resize Control** | CSS | CSS | - | - | ✓ | - | - | - | `disableAutosize` | - | - | ✓ | - | - | ✓ |
+| **Error State** | `aria-invalid` | `aria-invalid` | - | ✓ | `isInvalid` | `error` | `error` | `status` | `isInvalid` | - | - | - | `invalid` | `intent` | `invalid` |
+| **Helper Text** | - | - | - | ✓ | - | `helperText` | - | - | `description` | - | ✓ | - | `helperText` | `helperText` | - |
+| **Label Built-in** | - | - | - | ✓ | - | `label` | `label` | - | `label` | - | ✓ | `label` | `labelText` | `label` | `label` |
+| **Form Integration** | Nativo | Nativo | - | ✓ | Nativo | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Chakra | MUI | Mantine | AntD | NextUI | Fluent |
+|------|:----:|:------:|:---:|:-------:|:----:|:------:|:------:|
+| `value` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `placeholder` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `disabled` | ✓ | `isDisabled` | ✓ | ✓ | ✓ | `isDisabled` | ✓ |
+| `readOnly` | ✓ | `isReadOnly` | - | ✓ | - | `isReadOnly` | - |
+| `required` | ✓ | `isRequired` | `required` | `required` | - | `isRequired` | `required` |
+| `rows` | ✓ | ✓ | `rows` | ✓ | ✓ | `minRows` | ✓ |
+| `maxLength` | ✓ | ✓ | - | `maxLength` | `maxLength` | `maxLength` | `maxLength` |
+| `resize` | CSS | ✓ | - | - | - | `disableAutosize` | ✓ |
+| `autoSize` | CSS | - | `maxRows` | ✓ | ✓ | ✓ | - |
+| `error` | `aria-invalid` | `isInvalid` | `error` | `error` | `status` | `isInvalid` | - |
+| `variant` | - | ✓ | ✓ | ✓ | ✓ | ✓ | `appearance` |
+| `size` | - | ✓ | `size` | ✓ | ✓ | ✓ | `size` |
+| `showCount` | - | - | - | - | ✓ | - | - |
+| `clearable` | - | - | - | - | ✓ | ✓ | - |
+
+#### Analise por Categoria
+
+**Headless/Primitivos (maxima flexibilidade):**
+- **React Aria** - TextField com comportamento completo, label, description, error
+- **Headless UI** - Nao possui Textarea dedicado
+- **Ariakit** - Form primitives com integracao a11y
+
+**Styled/Opinionated (produtividade):**
+- **Chakra UI** - `resize` prop, `isInvalid`, integrado com FormControl
+- **MUI** - TextField com `multiline`, `maxRows`, `helperText`
+- **Mantine** - `autosize`, `minRows`/`maxRows`, integrado com Input.Wrapper
+- **Ant Design** - `autoSize`, `showCount`, `allowClear`, `status`
+
+**Hybrid (meio-termo):**
+- **Shadcn/ui** - Minimalista, `field-sizing-content`
+- **NextUI** - Variantes, auto-resize, `isClearable`
+- **ETUS** - Baseado em Shadcn, `field-sizing-content`
+
+**Enterprise/Legacy:**
+- **Fluent UI** - `appearance`, resize controls
+- **Carbon** - `enableCounter`, `invalid`, `light`/`dark`
+- **Blueprint** - `growVertically`, `intent` para estados
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Uso |
+|----------|-----|
+| `aria-invalid` | Quando campo tem erro de validacao |
+| `aria-required` | Quando campo e obrigatorio |
+| `aria-disabled` | Quando desabilitado (alem de `disabled`) |
+| `aria-describedby` | Referencia mensagem de erro/ajuda |
+| `aria-label` | Quando nao ha label visivel |
+| `aria-labelledby` | Referencia label externa |
+
+### Suporte a Teclado
+
+| Tecla | Acao |
+|-------|------|
+| `Tab` | Move foco para/do textarea |
+| `Shift + Tab` | Move foco para elemento anterior |
+| `Enter` | Insere nova linha |
+| `Ctrl + A` / `Cmd + A` | Seleciona todo texto |
+| `Ctrl + C` / `Cmd + C` | Copia texto selecionado |
+| `Ctrl + V` / `Cmd + V` | Cola texto |
+| `Ctrl + Z` / `Cmd + Z` | Desfaz ultima acao |
+
+### Focus Management
+
+```tsx
+// Focus visible apenas para navegacao por teclado
+focus-visible:border-ring
+focus-visible:ring-ring/50
+focus-visible:ring-[3px]
+```
+
+### Contraste de Cores
+
+Todos os pares de cores seguem WCAG 2.1 AA (minimo 4.5:1):
+
+| Estado | Foreground | Background | Ratio |
+|--------|------------|------------|-------|
+| Default | `--foreground` | `--background` | >= 4.5:1 |
+| Placeholder | `--muted-foreground` | `--background` | >= 4.5:1 |
+| Disabled | `--muted-foreground` | `--background` | >= 3:1 |
+| Error | `--destructive` | `--background` | >= 4.5:1 |
+
+### Screen Readers
+
+- Sempre associar com `<Label>` usando `htmlFor` ou wrapper `<Field>`
+- Usar `aria-describedby` para mensagens de erro e helper text
+- Anunciar limites de caracteres com `aria-live` quando relevante
+- Evitar placeholder como substituto de label
+
+### Reduced Motion
+
+```tsx
+// Transicoes respeitam preferencia do usuario
+transition-[color,box-shadow]
+// Em CSS:
+@media (prefers-reduced-motion: reduce) {
+  transition: none;
+}
+```
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature | ETUS | React Aria | Radix | Ariakit | Headless | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon | Blueprint | PrimeReact |
+|---------|:----:|:----------:|:-----:|:-------:|:--------:|:------:|:---:|:-------:|:----:|:------:|:------:|:------:|:---------:|:----------:|
+| **aria-invalid** | ✓ | ✓ | - | ✓ | - | ✓ | ✓ | ✓ | ~ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **aria-describedby** | Manual | ✓ | - | ✓ | - | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | - |
+| **Label association** | Manual | ✓ | - | ✓ | - | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Error announce** | Manual | ✓ | - | ✓ | - | ~ | ~ | ~ | - | ~ | ✓ | ✓ | ~ | - |
+| **Keyboard nav** | ✓ | ✓ | - | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Focus visible** | ✓ | ✓ | - | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Reduced motion** | ~ | ✓ | - | - | - | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | - | - |
+| **RTL support** | CSS | ✓ | - | - | - | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | - | - |
+| **Screen reader tested** | - | ✓ | - | ✓ | - | ~ | ✓ | ~ | ~ | ~ | ✓ | ✓ | ~ | - |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Nao suportado
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { Textarea } from "@etus/ui"
+
+function Example() {
+  return <Textarea placeholder="Digite sua mensagem..." />
+}
+```
+
+### Com Label (Campo Acessivel)
+
+```tsx
+import { Label, Textarea } from "@etus/ui"
+
+function Example() {
+  return (
+    <div className="space-y-2">
+      <Label htmlFor="message">Mensagem</Label>
+      <Textarea id="message" placeholder="Digite sua mensagem..." />
+    </div>
+  )
+}
+```
+
+### Com Field (Componente Compound)
+
+```tsx
+import { Field, Textarea } from "@etus/ui"
+
+function Example() {
+  return (
+    <Field>
+      <Field.Label>Descricao</Field.Label>
+      <Textarea placeholder="Descreva o produto..." />
+      <Field.Description>Maximo 500 caracteres</Field.Description>
+    </Field>
+  )
+}
+```
+
+### Controlado vs Nao-Controlado
+
+```tsx
+import { useState } from "react"
+import { Textarea } from "@etus/ui"
+
+// Controlado
+function ControlledExample() {
+  const [value, setValue] = useState("")
+
+  return (
+    <Textarea
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+      placeholder="Controlado..."
+    />
+  )
+}
+
+// Nao-controlado
+function UncontrolledExample() {
+  return (
+    <Textarea
+      defaultValue="Valor inicial"
+      name="description"
+    />
+  )
+}
+```
+
+### Com Limite de Caracteres
+
+```tsx
+import { useState } from "react"
+import { Label, Textarea } from "@etus/ui"
+
+function CharacterLimitExample() {
+  const [value, setValue] = useState("")
+  const maxLength = 280
+
+  return (
+    <div className="space-y-2">
+      <div className="flex justify-between">
+        <Label htmlFor="tweet">Sua mensagem</Label>
+        <span className="text-sm text-muted-foreground">
+          {value.length}/{maxLength}
+        </span>
+      </div>
+      <Textarea
+        id="tweet"
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        maxLength={maxLength}
+        placeholder="O que esta acontecendo?"
+      />
+    </div>
+  )
+}
+```
+
+### Estado de Erro
+
+```tsx
+import { Field, Textarea } from "@etus/ui"
+
+function ErrorExample() {
+  return (
+    <Field>
+      <Field.Label>Comentario</Field.Label>
+      <Textarea
+        aria-invalid="true"
+        aria-describedby="comment-error"
+        placeholder="Digite seu comentario..."
+        className="border-destructive"
+      />
+      <Field.Error id="comment-error">
+        O comentario deve ter pelo menos 10 caracteres.
+      </Field.Error>
+    </Field>
+  )
+}
+```
+
+### Desabilitado e Somente Leitura
+
+```tsx
+import { Textarea } from "@etus/ui"
+
+function StatesExample() {
+  return (
+    <div className="space-y-4">
+      {/* Desabilitado */}
+      <Textarea
+        disabled
+        value="Este campo esta desabilitado"
+      />
+
+      {/* Somente leitura */}
+      <Textarea
+        readOnly
+        value="Este campo e somente leitura"
+      />
+    </div>
+  )
+}
+```
+
+### Com Linhas Fixas
+
+```tsx
+import { Textarea } from "@etus/ui"
+
+function FixedRowsExample() {
+  return (
+    <Textarea
+      rows={4}
+      className="resize-none"
+      placeholder="4 linhas fixas, sem redimensionamento..."
+    />
+  )
+}
+```
+
+### Controle de Resize
+
+```tsx
+import { Textarea } from "@etus/ui"
+
+function ResizeExample() {
+  return (
+    <div className="space-y-4">
+      {/* Nenhum resize */}
+      <Textarea className="resize-none" placeholder="Sem resize" />
+
+      {/* Apenas vertical */}
+      <Textarea className="resize-y" placeholder="Resize vertical" />
+
+      {/* Apenas horizontal */}
+      <Textarea className="resize-x" placeholder="Resize horizontal" />
+
+      {/* Ambos (padrao) */}
+      <Textarea className="resize" placeholder="Resize em ambas direcoes" />
+    </div>
+  )
+}
+```
+
+### Com React Hook Form
+
+```tsx
+import { useForm } from "react-hook-form"
+import { zodResolver } from "@hookform/resolvers/zod"
+import { z } from "zod"
+import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from "@etus/ui"
+import { Textarea } from "@etus/ui"
+import { Button } from "@etus/ui"
+
+const schema = z.object({
+  bio: z.string()
+    .min(10, "A bio deve ter pelo menos 10 caracteres")
+    .max(500, "A bio deve ter no maximo 500 caracteres")
+})
+
+function FormExample() {
+  const form = useForm({
+    resolver: zodResolver(schema),
+    defaultValues: { bio: "" }
+  })
+
+  const onSubmit = (data: z.infer<typeof schema>) => {
+    console.log(data)
+  }
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
+        <FormField
+          control={form.control}
+          name="bio"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Bio</FormLabel>
+              <FormControl>
+                <Textarea
+                  placeholder="Conte um pouco sobre voce..."
+                  {...field}
+                />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <Button type="submit">Salvar</Button>
+      </form>
+    </Form>
+  )
+}
+```
+
+### Responsividade
+
+```tsx
+import { Textarea } from "@etus/ui"
+
+function ResponsiveExample() {
+  return (
+    <Textarea
+      className="min-h-24 md:min-h-32 lg:min-h-40"
+      placeholder="Altura responsiva..."
+    />
+  )
+}
+```
+
+### Com Container Queries
+
+```tsx
+import { Textarea } from "@etus/ui"
+
+function ContainerQueryExample() {
+  return (
+    <div className="@container">
+      <Textarea
+        className="min-h-16 @sm:min-h-24 @md:min-h-32"
+        placeholder="Altura baseada no container..."
+      />
+    </div>
+  )
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// Textarea.test.tsx
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, expect, it, vi } from "vitest"
+import { Textarea } from "./Textarea"
+
+describe("Textarea", () => {
+  it("renders correctly", () => {
+    render(<Textarea placeholder="Test" />)
+    expect(screen.getByRole("textbox")).toBeInTheDocument()
+  })
+
+  it("displays placeholder text", () => {
+    render(<Textarea placeholder="Digite aqui..." />)
+    expect(screen.getByPlaceholderText("Digite aqui...")).toBeInTheDocument()
+  })
+
+  it("has data-slot attribute", () => {
+    render(<Textarea />)
+    expect(screen.getByRole("textbox")).toHaveAttribute("data-slot", "textarea")
+  })
+
+  it("merges custom className", () => {
+    render(<Textarea className="custom-class" />)
+    expect(screen.getByRole("textbox")).toHaveClass("custom-class")
+  })
+
+  it("forwards ref correctly", () => {
+    const ref = { current: null }
+    render(<Textarea ref={ref} />)
+    expect(ref.current).toBeInstanceOf(HTMLTextAreaElement)
+  })
+})
+```
+
+### Testes de Interacao
+
+```tsx
+describe("Textarea interactions", () => {
+  it("calls onChange when typing", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(<Textarea onChange={handleChange} />)
+    await user.type(screen.getByRole("textbox"), "Hello")
+
+    expect(handleChange).toHaveBeenCalledTimes(5) // Uma vez por caractere
+  })
+
+  it("updates value when typing", async () => {
+    const user = userEvent.setup()
+
+    render(<Textarea />)
+    const textarea = screen.getByRole("textbox")
+
+    await user.type(textarea, "Test message")
+    expect(textarea).toHaveValue("Test message")
+  })
+
+  it("respects maxLength", async () => {
+    const user = userEvent.setup()
+
+    render(<Textarea maxLength={5} />)
+    const textarea = screen.getByRole("textbox")
+
+    await user.type(textarea, "1234567890")
+    expect(textarea).toHaveValue("12345")
+  })
+
+  it("does not accept input when disabled", async () => {
+    const user = userEvent.setup()
+
+    render(<Textarea disabled defaultValue="Initial" />)
+    const textarea = screen.getByRole("textbox")
+
+    await user.type(textarea, " more text")
+    expect(textarea).toHaveValue("Initial")
+  })
+
+  it("handles focus and blur events", async () => {
+    const user = userEvent.setup()
+    const handleFocus = vi.fn()
+    const handleBlur = vi.fn()
+
+    render(<Textarea onFocus={handleFocus} onBlur={handleBlur} />)
+    const textarea = screen.getByRole("textbox")
+
+    await user.click(textarea)
+    expect(handleFocus).toHaveBeenCalledTimes(1)
+
+    await user.tab()
+    expect(handleBlur).toHaveBeenCalledTimes(1)
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("Textarea accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <label>
+        Mensagem
+        <Textarea />
+      </label>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("has no violations with aria-label", async () => {
+    const { container } = render(
+      <Textarea aria-label="Mensagem" />
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("is focusable", () => {
+    render(<Textarea />)
+    const textarea = screen.getByRole("textbox")
+    textarea.focus()
+    expect(textarea).toHaveFocus()
+  })
+
+  it("is not focusable when disabled", () => {
+    render(<Textarea disabled />)
+    const textarea = screen.getByRole("textbox")
+    expect(textarea).toBeDisabled()
+  })
+
+  it("supports aria-invalid for error state", () => {
+    render(<Textarea aria-invalid="true" />)
+    expect(screen.getByRole("textbox")).toHaveAttribute("aria-invalid", "true")
+  })
+
+  it("supports aria-describedby for error messages", () => {
+    render(
+      <>
+        <Textarea aria-describedby="error-msg" />
+        <span id="error-msg">Erro de validacao</span>
+      </>
+    )
+    expect(screen.getByRole("textbox")).toHaveAttribute("aria-describedby", "error-msg")
+  })
+})
+```
+
+### Testes de Formulario
+
+```tsx
+describe("Textarea in forms", () => {
+  it("submits value with form", async () => {
+    const user = userEvent.setup()
+    const handleSubmit = vi.fn((e) => {
+      e.preventDefault()
+      const formData = new FormData(e.target)
+      return formData.get("message")
+    })
+
+    render(
+      <form onSubmit={handleSubmit}>
+        <Textarea name="message" defaultValue="Test message" />
+        <button type="submit">Submit</button>
+      </form>
+    )
+
+    await user.click(screen.getByRole("button"))
+    expect(handleSubmit).toHaveBeenCalled()
+  })
+
+  it("validates required field", () => {
+    render(
+      <form>
+        <Textarea required />
+      </form>
+    )
+    expect(screen.getByRole("textbox")).toBeRequired()
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na analise comparativa com 14 design systems, as seguintes features sao candidatas para implementacao futura:
+
+### Prioridade Alta
+
+#### `autoSize` com min/max rows
+
+Controle granular de auto-resize com limites.
+
+```tsx
+// Proposta de API
+interface TextareaProps {
+  autoSize?: boolean | {
+    minRows?: number
+    maxRows?: number
+  }
+}
+
+// Uso
+<Textarea autoSize />
+<Textarea autoSize={{ minRows: 2, maxRows: 6 }} />
+```
+
+**Referencias:** Mantine (`minRows`/`maxRows`), AntD (`autoSize.minRows`), MUI (`maxRows`)
+
+#### `variant` + `size`
+
+Variantes visuais e tamanhos consistentes com outros inputs.
+
+```tsx
+// Proposta de API
+interface TextareaProps {
+  variant?: "default" | "filled" | "flushed" | "unstyled"
+  size?: "sm" | "default" | "lg"
+}
+
+// Uso
+<Textarea variant="filled" size="lg" />
+```
+
+**Referencias:** Chakra, MUI, Mantine, NextUI
+
+### Prioridade Media
+
+#### `showCount`
+
+Contador de caracteres integrado.
+
+```tsx
+// Proposta de API
+interface TextareaProps {
+  showCount?: boolean | {
+    formatter: (info: { count: number; maxLength?: number }) => string
+  }
+  maxLength?: number
+}
+
+// Uso
+<Textarea showCount maxLength={280} />
+```
+
+**Referencias:** AntD (`showCount`), Carbon (`enableCounter`)
+
+#### Melhorias de A11y
+
+```tsx
+// aria-describedby automatico com Field
+<Field>
+  <Field.Label>Bio</Field.Label>
+  <Textarea /> {/* aria-describedby auto-vinculado */}
+  <Field.Description>Maximo 500 caracteres</Field.Description>
+  <Field.Error>Campo obrigatorio</Field.Error>
+</Field>
+```
+
+**Referencias:** React Aria, Ariakit
+
+### Prioridade Baixa
+
+#### `clearable`
+
+Botao para limpar conteudo.
+
+```tsx
+// Proposta de API
+interface TextareaProps {
+  clearable?: boolean
+  onClear?: () => void
+}
+
+// Uso
+<Textarea clearable onClear={() => console.log("cleared")} />
+```
+
+**Referencias:** AntD (`allowClear`), NextUI (`isClearable`)
+
+#### `status` / `intent`
+
+Estados visuais semanticos.
+
+```tsx
+// Proposta de API
+interface TextareaProps {
+  status?: "default" | "success" | "warning" | "error"
+}
+
+// Uso
+<Textarea status="success" />
+```
+
+**Referencias:** AntD (`status`), Blueprint (`intent`)
+
+### Decisoes de Design
+
+| Feature | Recomendacao | Justificativa |
+|---------|--------------|---------------|
+| `autoSize` | ✅ Implementar | `field-sizing-content` ja resolve, mas min/max rows e util |
+| `variant`/`size` | ✅ Implementar | Consistencia com outros inputs |
+| `showCount` | ⚠️ Avaliar | Pode ser feito via composicao |
+| `clearable` | ❌ Evitar | Incomum em textareas, UX questionavel |
+| `status` | ❌ Evitar | Usar `aria-invalid` + className |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Documentacao Textarea | GitHub |
+|---------------|----------------------|--------|
+| **Shadcn/ui** | [Textarea](https://ui.shadcn.com/docs/components/textarea) | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
+| **Radix UI** | N/A (primitivo nativo) | [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** | [Textarea](https://chakra-ui.com/docs/components/textarea) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **MUI** | [TextField multiline](https://mui.com/material-ui/react-text-field/#multiline) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Mantine** | [Textarea](https://mantine.dev/core/textarea/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Ant Design** | [Input.TextArea](https://ant.design/components/input#inputtextarea) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
+| **NextUI** | [Textarea](https://nextui.org/docs/components/textarea) | [nextui-org/nextui](https://github.com/nextui-org/nextui) |
+| **Headless UI** | N/A | [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui) |
+| **Ariakit** | [Form](https://ariakit.org/components/form) | [ariakit/ariakit](https://github.com/ariakit/ariakit) |
+| **Fluent UI** | [Textarea](https://react.fluentui.dev/?path=/docs/components-textarea--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | [TextArea](https://carbondesignsystem.com/components/text-area/usage/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint** | [TextArea](https://blueprintjs.com/docs/#core/components/text-area) | [palantir/blueprint](https://github.com/palantir/blueprint) |
+| **PrimeReact** | [InputTextarea](https://primereact.org/inputtextarea/) | [primefaces/primereact](https://github.com/primefaces/primereact) |
+
+### Especificacoes e Padroes
+
+- [WAI-ARIA APG - No specific pattern](https://www.w3.org/WAI/ARIA/apg/) (textarea e elemento nativo)
+- [WCAG 2.1 Success Criteria](https://www.w3.org/WAI/WCAG21/quickref/)
+- [MDN - Textarea Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea)
+- [HTML Spec - Textarea](https://html.spec.whatwg.org/multipage/form-elements.html#the-textarea-element)
+
+### Ferramentas Utilizadas
+
+- [Tailwind CSS v4](https://tailwindcss.com/docs)
+- [field-sizing CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/field-sizing)