# RadioButton

![Status](https://img.shields.io/badge/status-stable-brightgreen)

Componente de botão de opção (radio button) individual com integração nativa ao Angular Forms. Permite seleção única em grupos, utilizando o atributo `name` para garantir exclusividade. Pode ser usado isolado ou em conjunto com `RadioButtonGroupComponent`.

## Quando usar

- Seleção exclusiva entre duas ou mais opções mutuamente exclusivas
- Formulários onde o usuário deve escolher exatamente uma opção de um conjunto pequeno e visível

## Quando não usar

- Para seleção de múltiplas opções simultaneamente — use `Checkbox`
- Para conjuntos grandes de opções — use `Select` (dropdown)
- Para toggle simples entre dois estados — use `Switch`

## Instalação

```typescript
import { RadioButtonComponent } from '@seniorsistemas/angular-components/radio-button';

@Component({
  standalone: true,
  imports: [RadioButtonComponent, FormsModule],
})
export class MeuComponent {}
```

## Uso básico

```html
<s-radiobutton
  value="opcaoA"
  name="minhasOpcoes"
  label="Opção A"
  [(ngModel)]="selecionado"
></s-radiobutton>
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `label` | `string` | — | Sim | Texto exibido ao lado do botão de opção |
| `name` | `string` | — | Sim | Nome do grupo. Deve ser igual para todos os botões do mesmo grupo |
| `value` | `unknown` | — | Sim | Valor associado ao botão. Emitido ao formulário quando selecionado |
| `buttonDisabled` | `boolean` | `false` | Não | Two-way binding para desabilitar o botão individualmente |
| `inputId` | `string` | `'RadioButton_X'` | Não | ID único do `<input>` interno, usado para acessibilidade |

### Outputs

| Evento | Tipo | Descrição |
|--------|------|-----------|
| `focusedInput` | `OutputEmitterRef<FocusEvent>` | Emitido quando o campo interno recebe foco |
| `inputFocusLost` | `OutputEmitterRef<FocusEvent>` | Emitido quando o campo interno perde o foco |

## Exemplos

### Grupo com ngModel

```html
<div style="display: flex; flex-direction: column; gap: 8px;">
  <s-radiobutton value="BR" name="paises" label="Brasil" [(ngModel)]="selecionado"></s-radiobutton>
  <s-radiobutton value="JP" name="paises" label="Japão" [(ngModel)]="selecionado"></s-radiobutton>
  <s-radiobutton value="CA" name="paises" label="Canadá" [(ngModel)]="selecionado"></s-radiobutton>
</div>
<p>Selecionado: {{ selecionado }}</p>
```

### Grupo com Reactive Forms

```html
<form [formGroup]="form">
  <s-radiobutton value="BR" name="pais" label="Brasil" formControlName="pais"></s-radiobutton>
  <s-radiobutton value="JP" name="pais" label="Japão" formControlName="pais"></s-radiobutton>
  <s-radiobutton value="CA" name="pais" label="Canadá" formControlName="pais"></s-radiobutton>
</form>
```

### Com item desabilitado

```html
<s-radiobutton value="BR" name="paises" label="Brasil" [(ngModel)]="selecionado"></s-radiobutton>
<s-radiobutton value="JP" name="paises" label="Japão (indisponível)" [(ngModel)]="selecionado" [buttonDisabled]="true"></s-radiobutton>
<s-radiobutton value="CA" name="paises" label="Canadá" [(ngModel)]="selecionado"></s-radiobutton>
```

### Com ID customizado (para testes ou acessibilidade)

```html
<s-radiobutton
  value="opcaoA"
  name="grupo"
  label="Opção A"
  inputId="radio-opcao-a"
  [(ngModel)]="selecionado"
></s-radiobutton>
```

## Acessibilidade

- Cada botão é um `<input type="radio">` nativo, totalmente acessível por teclado e leitores de tela
- Navegação por teclado:
  - `Tab`: move o foco para o grupo de radio buttons
  - `Setas ↑↓` ou `←→`: navegam entre as opções do mesmo grupo (`name`)
  - `Space` ou `Enter`: seleciona o botão em foco
- O `label` é associado ao `<input>` via `inputId`, garantindo clicabilidade e semântica correta
- Itens desabilitados são sinalizados com `disabled` nativo

## Componentes relacionados

- [`RadioButtonGroup`](../radio-button-group/README.md) — agrupamento com layout e registro centralizado de radio buttons
- [`Checkbox`](../checkbox/README.md) — seleção múltipla
- [`Switch`](../switch/README.md) — alternador booleano simples