@etus/ui 0.1.0

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

@@ -0,0 +1,908 @@
+# RadioGroup
+
+## Visão Geral
+
+O **RadioGroup** e um componente de selecao mutuamente exclusiva que permite ao usuario escolher uma unica opcao de um conjunto. Como elemento de formulario, segue o padrao WAI-ARIA Radio Group e e construido sobre o Radix UI para garantir acessibilidade completa.
+
+### Casos de Uso
+
+- Selecao de uma unica opcao entre multiplas alternativas (ex: metodo de pagamento)
+- Configuracoes com opcoes mutuamente exclusivas (ex: tema claro/escuro)
+- Formularios onde apenas uma resposta e valida (ex: genero, tipo de conta)
+- Preferencias do usuario com opcoes predefinidas
+- Filtros de busca com opcoes exclusivas
+
+### Classificacao
+
+**Categoria:** Forms (Formularios)
+**Dependencias:** `@radix-ui/react-radio-group`, `lucide-react`
+
+---
+
+## Design Specs
+
+### Estrutura do Componente
+
+O RadioGroup segue um padrao de compound components:
+
+```
+RadioGroup (Root)
+└── RadioGroupItem (Item)
+    └── RadioGroupIndicator (interno)
+```
+
+### Tamanhos
+
+| Tamanho | Dimensao | Indicador | Uso |
+|---------|----------|-----------|-----|
+| `default` | `size-4` (16px) | `size-2` (8px) | Uso geral em formularios |
+
+> **Nota:** Atualmente apenas um tamanho e suportado. Variantes de tamanho podem ser adicionadas futuramente.
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Default | - | Borda `border-input`, fundo transparente |
+| Hover | - | Herda do browser |
+| Focus | `focus-visible:ring-[3px]` | Ring com `ring-ring/50`, borda `border-ring` |
+| Checked | `data-state="checked"` | Exibe indicador circular preenchido |
+| Disabled | `disabled:opacity-50` | 50% opacidade, cursor not-allowed |
+| Invalid | `aria-invalid="true"` | Borda e ring `destructive` |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--color-input          /* Borda padrao */
+--color-primary        /* Indicador checked */
+--color-ring           /* Focus ring */
+--color-destructive    /* Estado invalido */
+
+/* Espacamento */
+gap-3                  /* Espacamento entre items (12px) */
+
+/* Bordas */
+border                 /* 1px solid */
+rounded-full           /* Circular (50%) */
+
+/* Sombras */
+shadow-xs              /* Sombra sutil */
+
+/* Transicoes */
+transition-[color,box-shadow]
+```
+
+### data-slot
+
+```html
+<div data-slot="radio-group">
+  <button data-slot="radio-group-item">
+    <span data-slot="radio-group-indicator">
+      <!-- CircleIcon -->
+    </span>
+  </button>
+</div>
+```
+
+---
+
+## API
+
+### RadioGroup (Root)
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `value` | `string` | - | Valor do item selecionado (controlado) |
+| `defaultValue` | `string` | - | Valor inicial (nao-controlado) |
+| `onValueChange` | `(value: string) => void` | - | Callback quando valor muda |
+| `disabled` | `boolean` | `false` | Desabilita todos os items |
+| `required` | `boolean` | `false` | Marca como obrigatorio |
+| `name` | `string` | - | Nome do campo para formularios |
+| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | Direcao do layout |
+| `dir` | `"ltr" \| "rtl"` | - | Direcao do texto |
+| `loop` | `boolean` | `true` | Permite loop na navegacao por teclado |
+| `className` | `string` | - | Classes CSS adicionais |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+### RadioGroupItem
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `value` | `string` | **obrigatorio** | Valor unico do item |
+| `disabled` | `boolean` | `false` | Desabilita este item especifico |
+| `required` | `boolean` | `false` | Marca como obrigatorio |
+| `className` | `string` | - | Classes CSS adicionais |
+
+> Herda todas as props de `React.ComponentProps<"button">`
+
+### Callbacks
+
+| Callback | Tipo | Descricao |
+|----------|------|-----------|
+| `onValueChange` | `(value: string) => void` | Disparado quando o valor selecionado muda |
+
+### TypeScript
+
+```typescript
+import type { ComponentProps } from "react"
+import type * as RadioGroupPrimitive from "@radix-ui/react-radio-group"
+
+// Props do RadioGroup
+type RadioGroupProps = ComponentProps<typeof RadioGroupPrimitive.Root>
+
+// Props do RadioGroupItem
+type RadioGroupItemProps = ComponentProps<typeof RadioGroupPrimitive.Item>
+
+// Tipos uteis
+type RadioGroupOrientation = "horizontal" | "vertical"
+type RadioGroupDirection = "ltr" | "rtl"
+```
+
+### 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 |
+|---------|:----:|:------:|:-----:|:----------:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|:---------:|:----------:|
+| Compound Components | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Controlled/Uncontrolled | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Orientacao | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Disabled (grupo) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Disabled (item) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Variantes visuais | - | - | - | ~ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ | - | ✓ |
+| Tamanhos | - | - | - | ~ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ | ✓ | ✓ |
+| Cores/colorScheme | - | - | - | - | ✓ | ✓ | ✓ | - | ✓ | - | - | - | - | - | - |
+| Descricao/Helper | - | - | - | ✓ | ✓ | ✓ | ✓ | - | ✓ | - | - | - | ✓ | - | - |
+| RTL Support | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ | ✓ | - | - |
+| Keyboard Loop | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - |
+| Error State | ✓ | ✓ | ~ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | - | - |
+| Custom Indicator | - | - | ~ | ✓ | - | ✓ | ✓ | - | ✓ | ✓ | ✓ | - | - | - | ✓ |
+| Radio Cards | - | - | - | - | - | - | ✓ | - | - | ✓ | - | - | ✓ | - | - |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Nao suportado
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Shadcn | Radix | Chakra | MUI | Mantine | AntD | NextUI |
+|------|:----:|:------:|:-----:|:------:|:---:|:-------:|:----:|:------:|
+| `value` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `defaultValue` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `onChange` | `onValueChange` | `onValueChange` | `onValueChange` | `onChange` | `onChange` | `onChange` | `onChange` | `onValueChange` |
+| `disabled` | ✓ | ✓ | ✓ | `isDisabled` | ✓ | ✓ | ✓ | `isDisabled` |
+| `size` | - | - | - | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `color` | - | - | - | `colorScheme` | `color` | `color` | - | `color` |
+| `orientation` | ✓ | ✓ | ✓ | - | `row` | ✓ | - | `orientation` |
+| `name` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Elemento | Uso |
+|----------|----------|-----|
+| `role="radiogroup"` | RadioGroup | Identifica o grupo de radios |
+| `role="radio"` | RadioGroupItem | Identifica cada opcao |
+| `aria-checked` | RadioGroupItem | Indica estado selecionado |
+| `aria-disabled` | RadioGroupItem | Indica estado desabilitado |
+| `aria-required` | RadioGroup | Indica campo obrigatorio |
+| `aria-invalid` | RadioGroupItem | Indica estado de erro |
+| `aria-labelledby` | RadioGroup | Referencia ao label do grupo |
+| `aria-describedby` | RadioGroup | Referencia a descricao/erro |
+
+### Suporte a Teclado
+
+| Tecla | Acao |
+|-------|------|
+| `Tab` | Move foco para dentro/fora do grupo |
+| `Space` | Seleciona o item focado |
+| `Arrow Down` / `Arrow Right` | Move para proximo item (e seleciona) |
+| `Arrow Up` / `Arrow Left` | Move para item anterior (e seleciona) |
+| `Home` | Move para primeiro item |
+| `End` | Move para ultimo item |
+
+### Focus Management
+
+```tsx
+// Focus visible apenas para navegacao por teclado
+focus-visible:border-ring
+focus-visible:ring-ring/50
+focus-visible:ring-[3px]
+```
+
+O foco se move automaticamente entre items ao usar setas, seguindo o padrao "roving tabindex" do WAI-ARIA.
+
+### Contraste de Cores
+
+Todos os pares de cores seguem WCAG 2.1 AA (minimo 4.5:1):
+
+| Estado | Foreground | Background | Ratio |
+|--------|------------|------------|-------|
+| Default | `border-input` | transparent | 4.5:1+ |
+| Checked | `fill-primary` | transparent | 4.5:1+ |
+| Focus | `ring-ring` | transparent | 4.5:1+ |
+| Invalid | `border-destructive` | transparent | 4.5:1+ |
+
+### Screen Readers
+
+- O grupo e anunciado como "radio group" com seu label associado
+- Cada item e anunciado com seu label e estado (checked/not checked)
+- Mudancas de selecao sao anunciadas automaticamente
+- Items desabilitados sao anunciados como "dimmed" ou "unavailable"
+
+### Reduced Motion
+
+```tsx
+// Transicoes respeitam preferencia do usuario
+@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 |
+|---------|:----:|:----------:|:-----:|:-------:|:--------:|:------:|:---:|:-------:|:----:|:------:|:------:|:------:|:---------:|:----------:|
+| WAI-ARIA Pattern | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ~ | ✓ | ✓ | ✓ | ~ | ~ |
+| Keyboard Nav | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Roving Tabindex | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | - | - |
+| Focus Visible | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ~ | ✓ | ✓ | ✓ | ✓ | ~ |
+| Screen Reader | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ~ | ✓ | ✓ | ✓ | ~ | ~ |
+| RTL Support | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | - | - |
+| High Contrast | ~ | ✓ | ~ | ~ | - | ~ | ✓ | ~ | - | - | ✓ | ✓ | - | - |
+| Error Announce | ✓ | ✓ | ~ | ✓ | - | ✓ | ✓ | ✓ | ~ | ~ | ✓ | ✓ | - | - |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Nao suportado
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { RadioGroup, RadioGroupItem } from "@etus/ui"
+import { Label } from "@etus/ui"
+
+function Example() {
+  return (
+    <RadioGroup defaultValue="option-1">
+      <div className="flex items-center gap-2">
+        <RadioGroupItem value="option-1" id="option-1" />
+        <Label htmlFor="option-1">Opcao 1</Label>
+      </div>
+      <div className="flex items-center gap-2">
+        <RadioGroupItem value="option-2" id="option-2" />
+        <Label htmlFor="option-2">Opcao 2</Label>
+      </div>
+      <div className="flex items-center gap-2">
+        <RadioGroupItem value="option-3" id="option-3" />
+        <Label htmlFor="option-3">Opcao 3</Label>
+      </div>
+    </RadioGroup>
+  )
+}
+```
+
+### Controlado
+
+```tsx
+import { useState } from "react"
+import { RadioGroup, RadioGroupItem } from "@etus/ui"
+import { Label } from "@etus/ui"
+
+function ControlledExample() {
+  const [value, setValue] = useState("comfortable")
+
+  return (
+    <RadioGroup value={value} onValueChange={setValue}>
+      <div className="flex items-center gap-2">
+        <RadioGroupItem value="default" id="r1" />
+        <Label htmlFor="r1">Padrao</Label>
+      </div>
+      <div className="flex items-center gap-2">
+        <RadioGroupItem value="comfortable" id="r2" />
+        <Label htmlFor="r2">Confortavel</Label>
+      </div>
+      <div className="flex items-center gap-2">
+        <RadioGroupItem value="compact" id="r3" />
+        <Label htmlFor="r3">Compacto</Label>
+      </div>
+    </RadioGroup>
+  )
+}
+```
+
+### Orientacao Horizontal
+
+```tsx
+import { RadioGroup, RadioGroupItem } from "@etus/ui"
+import { Label } from "@etus/ui"
+
+function HorizontalExample() {
+  return (
+    <RadioGroup defaultValue="card" orientation="horizontal" className="flex gap-4">
+      <div className="flex items-center gap-2">
+        <RadioGroupItem value="card" id="card" />
+        <Label htmlFor="card">Cartao</Label>
+      </div>
+      <div className="flex items-center gap-2">
+        <RadioGroupItem value="pix" id="pix" />
+        <Label htmlFor="pix">PIX</Label>
+      </div>
+      <div className="flex items-center gap-2">
+        <RadioGroupItem value="boleto" id="boleto" />
+        <Label htmlFor="boleto">Boleto</Label>
+      </div>
+    </RadioGroup>
+  )
+}
+```
+
+### Com Descricao
+
+```tsx
+import { RadioGroup, RadioGroupItem } from "@etus/ui"
+import { Label } from "@etus/ui"
+
+function WithDescriptionExample() {
+  return (
+    <RadioGroup defaultValue="startup">
+      <div className="flex items-start gap-3">
+        <RadioGroupItem value="startup" id="startup" className="mt-1" />
+        <div className="grid gap-1">
+          <Label htmlFor="startup" className="font-medium">Startup</Label>
+          <p className="text-sm text-muted-foreground">
+            Ate 10 usuarios, ideal para pequenas equipes
+          </p>
+        </div>
+      </div>
+      <div className="flex items-start gap-3">
+        <RadioGroupItem value="business" id="business" className="mt-1" />
+        <div className="grid gap-1">
+          <Label htmlFor="business" className="font-medium">Business</Label>
+          <p className="text-sm text-muted-foreground">
+            Ate 100 usuarios, recursos avancados
+          </p>
+        </div>
+      </div>
+      <div className="flex items-start gap-3">
+        <RadioGroupItem value="enterprise" id="enterprise" className="mt-1" />
+        <div className="grid gap-1">
+          <Label htmlFor="enterprise" className="font-medium">Enterprise</Label>
+          <p className="text-sm text-muted-foreground">
+            Usuarios ilimitados, suporte dedicado
+          </p>
+        </div>
+      </div>
+    </RadioGroup>
+  )
+}
+```
+
+### Com Items Desabilitados
+
+```tsx
+import { RadioGroup, RadioGroupItem } from "@etus/ui"
+import { Label } from "@etus/ui"
+
+function DisabledItemsExample() {
+  return (
+    <RadioGroup defaultValue="approved">
+      <div className="flex items-center gap-2">
+        <RadioGroupItem value="pending" id="pending" disabled />
+        <Label htmlFor="pending" className="text-muted-foreground">
+          Pendente (indisponivel)
+        </Label>
+      </div>
+      <div className="flex items-center gap-2">
+        <RadioGroupItem value="approved" id="approved" />
+        <Label htmlFor="approved">Aprovado</Label>
+      </div>
+      <div className="flex items-center gap-2">
+        <RadioGroupItem value="rejected" id="rejected" />
+        <Label htmlFor="rejected">Rejeitado</Label>
+      </div>
+    </RadioGroup>
+  )
+}
+```
+
+### Grupo Desabilitado
+
+```tsx
+import { RadioGroup, RadioGroupItem } from "@etus/ui"
+import { Label } from "@etus/ui"
+
+function DisabledGroupExample() {
+  return (
+    <RadioGroup defaultValue="option-1" disabled>
+      <div className="flex items-center gap-2">
+        <RadioGroupItem value="option-1" id="d1" />
+        <Label htmlFor="d1" className="text-muted-foreground">Opcao 1</Label>
+      </div>
+      <div className="flex items-center gap-2">
+        <RadioGroupItem value="option-2" id="d2" />
+        <Label htmlFor="d2" className="text-muted-foreground">Opcao 2</Label>
+      </div>
+    </RadioGroup>
+  )
+}
+```
+
+### Com React Hook Form
+
+```tsx
+import { useForm } from "react-hook-form"
+import { zodResolver } from "@hookform/resolvers/zod"
+import { z } from "zod"
+import { RadioGroup, RadioGroupItem } from "@etus/ui"
+import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from "@etus/ui"
+
+const formSchema = z.object({
+  type: z.enum(["all", "mentions", "none"], {
+    required_error: "Selecione uma opcao de notificacao",
+  }),
+})
+
+function FormExample() {
+  const form = useForm<z.infer<typeof formSchema>>({
+    resolver: zodResolver(formSchema),
+  })
+
+  function onSubmit(data: z.infer<typeof formSchema>) {
+    console.log(data)
+  }
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
+        <FormField
+          control={form.control}
+          name="type"
+          render={({ field }) => (
+            <FormItem className="space-y-3">
+              <FormLabel>Notificacoes por email</FormLabel>
+              <FormControl>
+                <RadioGroup
+                  onValueChange={field.onChange}
+                  defaultValue={field.value}
+                  className="flex flex-col space-y-1"
+                >
+                  <FormItem className="flex items-center space-x-3 space-y-0">
+                    <FormControl>
+                      <RadioGroupItem value="all" />
+                    </FormControl>
+                    <FormLabel className="font-normal">
+                      Todas as notificacoes
+                    </FormLabel>
+                  </FormItem>
+                  <FormItem className="flex items-center space-x-3 space-y-0">
+                    <FormControl>
+                      <RadioGroupItem value="mentions" />
+                    </FormControl>
+                    <FormLabel className="font-normal">
+                      Apenas mencoes
+                    </FormLabel>
+                  </FormItem>
+                  <FormItem className="flex items-center space-x-3 space-y-0">
+                    <FormControl>
+                      <RadioGroupItem value="none" />
+                    </FormControl>
+                    <FormLabel className="font-normal">
+                      Nenhuma notificacao
+                    </FormLabel>
+                  </FormItem>
+                </RadioGroup>
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <button type="submit">Salvar</button>
+      </form>
+    </Form>
+  )
+}
+```
+
+### Cards de Selecao (Radio Cards)
+
+```tsx
+import { RadioGroup, RadioGroupItem } from "@etus/ui"
+import { Label } from "@etus/ui"
+import { CheckCircle2Icon } from "lucide-react"
+
+function RadioCardsExample() {
+  return (
+    <RadioGroup defaultValue="card" className="grid grid-cols-3 gap-4">
+      {[
+        { value: "card", label: "Cartao", description: "Credito ou debito" },
+        { value: "pix", label: "PIX", description: "Transferencia instantanea" },
+        { value: "boleto", label: "Boleto", description: "Ate 3 dias uteis" },
+      ].map((item) => (
+        <Label
+          key={item.value}
+          htmlFor={item.value}
+          className="flex cursor-pointer flex-col items-center justify-between rounded-md border-2 border-muted bg-popover p-4 hover:bg-accent hover:text-accent-foreground has-[[data-state=checked]]:border-primary [&:has([data-state=checked])]:border-primary"
+        >
+          <RadioGroupItem value={item.value} id={item.value} className="sr-only" />
+          <span className="text-sm font-medium">{item.label}</span>
+          <span className="text-xs text-muted-foreground">{item.description}</span>
+        </Label>
+      ))}
+    </RadioGroup>
+  )
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// RadioGroup.test.tsx
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, expect, it, vi } from "vitest"
+import { RadioGroup, RadioGroupItem } from "./RadioGroup"
+
+describe("RadioGroup", () => {
+  it("renders radio group correctly", () => {
+    render(
+      <RadioGroup>
+        <RadioGroupItem value="option-1" />
+      </RadioGroup>
+    )
+    expect(screen.getByRole("radiogroup")).toBeInTheDocument()
+    expect(screen.getByRole("radio")).toBeInTheDocument()
+  })
+
+  it("has data-slot attribute", () => {
+    render(
+      <RadioGroup>
+        <RadioGroupItem value="option-1" />
+      </RadioGroup>
+    )
+    expect(screen.getByRole("radiogroup")).toHaveAttribute("data-slot", "radio-group")
+    expect(screen.getByRole("radio")).toHaveAttribute("data-slot", "radio-group-item")
+  })
+
+  it("applies custom className", () => {
+    render(
+      <RadioGroup className="custom-class">
+        <RadioGroupItem value="option-1" className="item-class" />
+      </RadioGroup>
+    )
+    expect(screen.getByRole("radiogroup")).toHaveClass("custom-class")
+    expect(screen.getByRole("radio")).toHaveClass("item-class")
+  })
+
+  it("renders with default value", () => {
+    render(
+      <RadioGroup defaultValue="option-2">
+        <RadioGroupItem value="option-1" />
+        <RadioGroupItem value="option-2" />
+      </RadioGroup>
+    )
+    const radios = screen.getAllByRole("radio")
+    expect(radios[0]).not.toBeChecked()
+    expect(radios[1]).toBeChecked()
+  })
+})
+```
+
+### Testes de Interacao
+
+```tsx
+describe("RadioGroup interactions", () => {
+  it("calls onValueChange when selection changes", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(
+      <RadioGroup onValueChange={handleChange}>
+        <RadioGroupItem value="option-1" />
+        <RadioGroupItem value="option-2" />
+      </RadioGroup>
+    )
+
+    await user.click(screen.getAllByRole("radio")[1])
+    expect(handleChange).toHaveBeenCalledWith("option-2")
+  })
+
+  it("supports keyboard navigation", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(
+      <RadioGroup defaultValue="option-1" onValueChange={handleChange}>
+        <RadioGroupItem value="option-1" />
+        <RadioGroupItem value="option-2" />
+        <RadioGroupItem value="option-3" />
+      </RadioGroup>
+    )
+
+    const firstRadio = screen.getAllByRole("radio")[0]
+    await user.click(firstRadio)
+    await user.keyboard("{ArrowDown}")
+
+    expect(handleChange).toHaveBeenCalledWith("option-2")
+  })
+
+  it("prevents interaction when disabled", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(
+      <RadioGroup onValueChange={handleChange} disabled>
+        <RadioGroupItem value="option-1" />
+        <RadioGroupItem value="option-2" />
+      </RadioGroup>
+    )
+
+    await user.click(screen.getAllByRole("radio")[1])
+    expect(handleChange).not.toHaveBeenCalled()
+  })
+
+  it("prevents interaction on disabled item", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(
+      <RadioGroup onValueChange={handleChange}>
+        <RadioGroupItem value="option-1" />
+        <RadioGroupItem value="option-2" disabled />
+      </RadioGroup>
+    )
+
+    await user.click(screen.getAllByRole("radio")[1])
+    expect(handleChange).not.toHaveBeenCalled()
+  })
+
+  it("works as controlled component", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    const { rerender } = render(
+      <RadioGroup value="option-1" onValueChange={handleChange}>
+        <RadioGroupItem value="option-1" />
+        <RadioGroupItem value="option-2" />
+      </RadioGroup>
+    )
+
+    expect(screen.getAllByRole("radio")[0]).toBeChecked()
+
+    await user.click(screen.getAllByRole("radio")[1])
+    expect(handleChange).toHaveBeenCalledWith("option-2")
+
+    // Simula atualizacao do state
+    rerender(
+      <RadioGroup value="option-2" onValueChange={handleChange}>
+        <RadioGroupItem value="option-1" />
+        <RadioGroupItem value="option-2" />
+      </RadioGroup>
+    )
+
+    expect(screen.getAllByRole("radio")[1]).toBeChecked()
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("RadioGroup accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <RadioGroup aria-label="Opcoes">
+        <RadioGroupItem value="option-1" aria-label="Opcao 1" />
+        <RadioGroupItem value="option-2" aria-label="Opcao 2" />
+      </RadioGroup>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("has correct ARIA attributes", () => {
+    render(
+      <RadioGroup aria-label="Preferencias" required>
+        <RadioGroupItem value="option-1" />
+      </RadioGroup>
+    )
+
+    expect(screen.getByRole("radiogroup")).toHaveAttribute("aria-label", "Preferencias")
+    expect(screen.getByRole("radiogroup")).toHaveAttribute("aria-required", "true")
+  })
+
+  it("associates label with radio item", () => {
+    render(
+      <RadioGroup>
+        <RadioGroupItem value="option-1" id="opt1" aria-labelledby="label1" />
+        <label id="label1">Opcao 1</label>
+      </RadioGroup>
+    )
+
+    expect(screen.getByRole("radio")).toHaveAttribute("aria-labelledby", "label1")
+  })
+
+  it("announces checked state to screen readers", async () => {
+    const user = userEvent.setup()
+
+    render(
+      <RadioGroup>
+        <RadioGroupItem value="option-1" aria-label="Opcao 1" />
+        <RadioGroupItem value="option-2" aria-label="Opcao 2" />
+      </RadioGroup>
+    )
+
+    const radio = screen.getAllByRole("radio")[0]
+    expect(radio).toHaveAttribute("aria-checked", "false")
+
+    await user.click(radio)
+    expect(radio).toHaveAttribute("aria-checked", "true")
+  })
+
+  it("supports keyboard-only navigation", async () => {
+    const user = userEvent.setup()
+
+    render(
+      <RadioGroup defaultValue="option-1">
+        <RadioGroupItem value="option-1" aria-label="Opcao 1" />
+        <RadioGroupItem value="option-2" aria-label="Opcao 2" />
+        <RadioGroupItem value="option-3" aria-label="Opcao 3" />
+      </RadioGroup>
+    )
+
+    // Tab para focar no grupo
+    await user.tab()
+    expect(screen.getAllByRole("radio")[0]).toHaveFocus()
+
+    // Arrow para navegar
+    await user.keyboard("{ArrowDown}")
+    expect(screen.getAllByRole("radio")[1]).toHaveFocus()
+
+    // Home para ir ao primeiro
+    await user.keyboard("{Home}")
+    expect(screen.getAllByRole("radio")[0]).toHaveFocus()
+
+    // End para ir ao ultimo
+    await user.keyboard("{End}")
+    expect(screen.getAllByRole("radio")[2]).toHaveFocus()
+  })
+})
+```
+
+### Testes de Composicao
+
+```tsx
+describe("RadioGroup composition", () => {
+  it("works with Form components", () => {
+    render(
+      <form>
+        <fieldset>
+          <legend>Selecione uma opcao</legend>
+          <RadioGroup name="preference" defaultValue="a">
+            <RadioGroupItem value="a" id="a" />
+            <label htmlFor="a">A</label>
+            <RadioGroupItem value="b" id="b" />
+            <label htmlFor="b">B</label>
+          </RadioGroup>
+        </fieldset>
+      </form>
+    )
+
+    expect(screen.getByRole("radiogroup")).toBeInTheDocument()
+    expect(screen.getAllByRole("radio")).toHaveLength(2)
+  })
+
+  it("renders indicator only when checked", async () => {
+    const user = userEvent.setup()
+
+    render(
+      <RadioGroup>
+        <RadioGroupItem value="option-1" />
+        <RadioGroupItem value="option-2" />
+      </RadioGroup>
+    )
+
+    // Inicialmente nenhum indicador visivel
+    expect(screen.queryByTestId("indicator")).not.toBeInTheDocument()
+
+    // Apos selecao, indicador aparece
+    await user.click(screen.getAllByRole("radio")[0])
+    expect(screen.getAllByRole("radio")[0]).toHaveAttribute("data-state", "checked")
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na analise comparativa com 14 design systems, as seguintes features sao candidatas para implementacao futura:
+
+### Prioridade Alta
+
+1. **Variantes de tamanho (`size`)** - 10/14 DS implementam
+   - Adicionar `sm`, `md`, `lg` seguindo padrao do Checkbox
+
+2. **Descricao/Helper text** - 6/14 DS implementam
+   - Prop `description` para texto auxiliar abaixo do label
+
+3. **Estado de erro integrado** - 8/14 DS implementam
+   - Prop `isInvalid` com styling automatico
+
+### Prioridade Media
+
+4. **Variantes visuais** - 7/14 DS implementam
+   - `variant: "default" | "card"` para Radio Cards
+
+5. **Cores/colorScheme** - 5/14 DS implementam
+   - Prop `color` para customizar cor do indicador
+
+6. **Indicador customizado** - 5/14 DS implementam
+   - Slot/prop para customizar o icone indicador
+
+### Prioridade Baixa
+
+7. **Loading state** - 2/14 DS implementam
+   - Prop `isLoading` com spinner
+
+8. **Animacoes** - 4/14 DS implementam
+   - Transicoes suaves com Framer Motion
+
+### Decisoes de Design
+
+| Feature | Recomendacao | Justificativa |
+|---------|--------------|---------------|
+| `size` | Implementar | 10/14 DS; consistencia com Checkbox/Switch |
+| `description` | Implementar | 6/14 DS; melhora UX em forms complexos |
+| `isInvalid` | Implementar | Ja existe suporte via `aria-invalid`, falta wrapper |
+| `variant="card"` | Avaliar | 3/14 DS; util mas pode ser feito com composicao |
+| `color` | Nao implementar | 5/14 DS; vai contra tokens do design system |
+| `isLoading` | Nao implementar | 2/14 DS; nao faz sentido semantico |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Documentacao | GitHub |
+|---------------|--------------|--------|
+| **Shadcn/ui** | [Radio Group](https://ui.shadcn.com/docs/components/radio-group) | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
+| **Radix UI** | [Radio Group](https://www.radix-ui.com/primitives/docs/components/radio-group) | [radix-ui/primitives](https://github.com/radix-ui/primitives) |
+| **React Aria** | [RadioGroup](https://react-spectrum.adobe.com/react-aria/RadioGroup.html) | [adobe/react-spectrum](https://github.com/adobe/react-spectrum) |
+| **Chakra UI** | [Radio](https://chakra-ui.com/docs/components/radio) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **MUI** | [Radio](https://mui.com/material-ui/react-radio-button/) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Mantine** | [Radio](https://mantine.dev/core/radio/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Ant Design** | [Radio](https://ant.design/components/radio) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
+| **NextUI** | [RadioGroup](https://nextui.org/docs/components/radio-group) | [nextui-org/nextui](https://github.com/nextui-org/nextui) |
+| **Headless UI** | [RadioGroup](https://headlessui.com/react/radio-group) | [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui) |
+| **Ariakit** | [Radio](https://ariakit.org/components/radio) | [ariakit/ariakit](https://github.com/ariakit/ariakit) |
+| **Fluent UI** | [RadioGroup](https://react.fluentui.dev/?path=/docs/components-radiogroup) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | [RadioButton](https://carbondesignsystem.com/components/radio-button/usage/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint** | [RadioGroup](https://blueprintjs.com/docs/#core/components/radio) | [palantir/blueprint](https://github.com/palantir/blueprint) |
+| **PrimeReact** | [RadioButton](https://primereact.org/radiobutton/) | [primefaces/primereact](https://github.com/primefaces/primereact) |
+
+### Especificacoes e Padroes
+
+- [WAI-ARIA APG - Radio Group Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/)
+- [WCAG 2.1 Success Criteria](https://www.w3.org/WAI/WCAG21/quickref/)
+- [MDN - input type="radio"](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/radio)
+
+### Ferramentas Utilizadas
+
+- [Radix UI Radio Group](https://www.radix-ui.com/primitives/docs/components/radio-group)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [Lucide Icons](https://lucide.dev/icons/)