# Switch

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

Componente de chave tipo switch (liga/desliga) para alternar entre dois estados booleanos. Implementa `ControlValueAccessor` para uso em formulários Angular. Suporta rótulos personalizados para os estados verdadeiro e falso, além de modo somente leitura.

## Quando usar

- Ativar ou desativar funcionalidades ou configurações
- Preferências do usuário (notificações, atualizações automáticas)
- Qualquer contexto com decisão binária clara (ligado/desligado, ativo/inativo)

## Quando não usar

- Seleção de múltiplas opções — prefira `Checkbox`
- Escolha entre mais de dois estados — prefira `RadioButtonGroup` ou `SelectButton`
- Quando o estado precisa de confirmação antes de ser aplicado — prefira `Checkbox` com botão de submissão

## Instalação

```typescript
import { SwitchModule } from '@seniorsistemas/angular-components/switch';

@NgModule({ imports: [SwitchModule] })
export class MeuModule {}
```

## Uso básico

```html
<s-switch formControlName="ativo" trueLabel="Ativo" falseLabel="Inativo" />
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `value` | `boolean` | `false` | Não | Estado atual do switch |
| `trueLabel` | `string` | `'Ligado'` | Não | Rótulo exibido quando o valor é `true` |
| `falseLabel` | `string` | `'Desligado'` | Não | Rótulo exibido quando o valor é `false` |
| `disabled` | `boolean` | `false` | Não | Desabilita o componente, impedindo interação e alterações |
| `readonly` | `boolean` | `false` | Não | Impede alterações pelo usuário sem desabilitar visualmente o campo |
| `showStatusLabel` | `boolean` | `true` | Não | Controla se o label de status (trueLabel/falseLabel) é exibido |
| `inputId` | `string` | `undefined` | Não | ID do `<input>` interno para associação com `<label>` externo |
| `inputName` | `string` | `undefined` | Não | Atributo `name` do `<input>` interno |
| `label` | `string` | `undefined` | Não | Nome acessível descritivo para tecnologias assistivas (`aria-label`) |

### Outputs

| Evento | Tipo | Descrição |
|--------|------|-----------|
| `valueChanged` | `EventEmitter<boolean>` | Emitido quando o valor do switch muda, com o novo estado booleano |

## Exemplos

### Switch básico sem labels

```html
<s-switch formControlName="ativo"></s-switch>
```

### Com labels customizados

```html
<s-switch
  formControlName="notificacoes"
  trueLabel="Notificações ativadas"
  falseLabel="Notificações desativadas"
></s-switch>
```

### Integração com Reactive Forms

```html
<form [formGroup]="form" (ngSubmit)="salvar()">
  <s-switch
    formControlName="notificacoes"
    trueLabel="Notificações Ativadas"
    falseLabel="Notificações Desativadas"
  ></s-switch>
  <s-switch
    formControlName="marketing"
    trueLabel="Aceito receber ofertas"
    falseLabel="Não aceito ofertas"
  ></s-switch>
  <s-switch
    formControlName="atualizacoes"
    trueLabel="Atualizações automáticas"
    falseLabel="Atualizações manuais"
  ></s-switch>
  <button type="submit">Salvar Preferências</button>
</form>
```

### Somente leitura (readonly)

```html
<!-- Mantém aparência habilitada, mas bloqueia alterações -->
<s-switch [value]="true" trueLabel="Ativo" falseLabel="Inativo" [readonly]="true"></s-switch>
```

### Desabilitado

```html
<s-switch
  trueLabel="Habilitado"
  falseLabel="Desabilitado"
  [disabled]="true"
></s-switch>
```

## Acessibilidade

- O elemento interno é um `<input type="checkbox">` com `role="switch"`, garantindo semântica correta para leitores de tela
- Pode ser ativado/desativado com `Espaço` quando em foco
- O input recebe foco visual ao ser navegado por teclado (classe CSS `switch--focus` adicionada via `focusin`/`focusout`)
- O `inputId` permite associar um `<label>` externo para melhor acessibilidade
- O `label` define um `aria-label` descritivo quando não há label visual associado

## Componentes relacionados

- [`Checkbox`](../checkbox/README.md) — seleção de múltiplas opções independentes
- [`RadioButton`](../radio-button/README.md) — seleção única entre opções mutuamente exclusivas