# Button

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

Componente de botão versátil para ações do usuário, com suporte a ícones, tooltip, menu dropdown (tiered menu), badge, animações e diferentes prioridades visuais.

## Quando usar

- Acionar ações do usuário: salvar, cancelar, excluir, navegar
- Agrupar múltiplas ações relacionadas em um menu dropdown
- Botões de refresh com animação de rotação no ícone
- Toolbars com botões de ícone e tooltip

## Quando não usar

- Para navegação entre páginas — use `routerLink` em um elemento `<a>` para preservar semântica HTML
- Para formulários com múltiplos campos de ação — avalie se um `<button type="submit">` nativo não atende melhor
- Para exibir ícones puramente decorativos — use a tag de ícone diretamente

## Instalação

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

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

## Uso básico

```html
<s-button label="Salvar" priority="primary" (clicked)="salvar()" />
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `label` | `string` | `undefined` | não | Texto exibido dentro do botão |
| `priority` | `ButtonPriority` | `'primary'` | não | Prioridade visual: `'primary'`, `'secondary'`, `'danger'`, `'default'`, `'link'` |
| `iconClass` | `string` | `undefined` | não | Classe do ícone à esquerda do label (ex.: `'fa fa-save'`) |
| `rightIconClass` | `string` | `undefined` | não | Classe do ícone à direita do label |
| `disabled` | `boolean` | `false` | não | Desabilita o botão |
| `size` | `'default' \| 'small'` | `'default'` | não | Tamanho do botão |
| `tooltip` | `string` | `undefined` | não | Texto do tooltip ao passar o mouse |
| `tooltipPosition` | `TooltipPositions` | `'top'` | não | Posição do tooltip |
| `menuOptions` | `TieredMenuItemData[]` | `[]` | não | Itens do menu dropdown |
| `caret` | `boolean` | `true` | não | Exibe seta quando há menu dropdown |
| `animation` | `ButtonAnimations` | `undefined` | não | Animação no ícone (`'rotate'`) |
| `slide` | `boolean` | `false` | não | Expande o label ao passar o mouse (requer `priority: 'default'` ou `'link'`) |
| `auxiliary` | `boolean` | `false` | não | Bordas completamente arredondadas (estilo pill) |
| `badge` | `ButtonBadgeConfig` | `undefined` | não | Badge de notificação exibido sobre o botão |
| `iconColor` | `string` | `undefined` | não | Cor personalizada para o ícone |
| `styleClass` | `string` | `''` | não | Classes CSS adicionais |
| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | não | Tipo do elemento `<button>` HTML |
| `id` | `string` | `s-button-{hash}` | não | ID do elemento no DOM |
| `baseZIndex` | `number` | `0` | não | Z-index base do menu dropdown |
| `menuAriaLabel` | `string` | `undefined` | não | Rótulo ARIA do menu associado |

### Outputs

| Evento | Tipo | Descrição |
|--------|------|-----------|
| `clicked` | `EventEmitter<any>` | Emitido ao clicar no botão (quando não desabilitado) |

### Tipos

```typescript
type ButtonPriority = 'default' | 'primary' | 'secondary' | 'link' | 'danger';

type ButtonAnimations = 'rotate';

interface ButtonBadgeConfig {
  text?: string;
  iconClass?: string;
  color: BadgeColors; // 'red' | 'orange' | 'yellow' | 'blue' | 'green' | 'gray'
}
```

## Exemplos

### Prioridades disponíveis

```html
<s-button label="Primário" priority="primary"></s-button>
<s-button label="Secundário" priority="secondary"></s-button>
<s-button label="Padrão" priority="default"></s-button>
<s-button label="Perigo" priority="danger" iconClass="fa fa-trash"></s-button>
<s-button label="Link" priority="link"></s-button>
```

### Com ícone e tooltip

```html
<!-- Botão apenas com ícone — use sempre tooltip para acessibilidade -->
<s-button iconClass="fa fa-trash" priority="secondary" tooltip="Excluir item"></s-button>

<!-- Botão com ícone à esquerda -->
<s-button label="Salvar" iconClass="fa fa-save" priority="primary"></s-button>

<!-- Botão com ícone à direita -->
<s-button label="Avançar" rightIconClass="fa fa-arrow-right" priority="primary"></s-button>
```

### Com menu dropdown

```html
<s-button
  label="Ações"
  iconClass="fa fa-ellipsis-v"
  priority="secondary"
  [menuOptions]="opcoes">
</s-button>
```

```typescript
opcoes = [
  { label: 'Editar', iconClass: 'fa fa-edit', command: () => this.editar() },
  { label: 'Excluir', iconClass: 'fa fa-trash', command: () => this.excluir() },
  { divider: true },
  { label: 'Configurações', iconClass: 'fa fa-cog', command: () => this.configurar() },
];
```

### Com badge de notificação

```html
<s-button
  label="Notificações"
  iconClass="fa fa-bell"
  priority="secondary"
  [badge]="{ text: '5', color: 'red' }">
</s-button>
```

### Com animação de rotação (refresh)

```html
<s-button
  label="Recarregar"
  iconClass="fa fa-sync"
  animation="rotate"
  priority="primary"
  (clicked)="recarregar()">
</s-button>
```

## Acessibilidade

- O componente renderiza um elemento `<button>` nativo, totalmente acessível via teclado
- Use **Tab** para focar e **Enter** ou **Space** para acionar
- Botões com apenas ícone devem sempre ter `tooltip` definido para comunicar a ação a leitores de tela
- O `menuAriaLabel` descreve o menu associado para tecnologias assistivas

## Componentes relacionados

- [`Badge`](../badge/README.md) — rótulos visuais; usado internamente pelo badge do botão