# GridMenu

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

Componente de menu em grade que exibe uma coleção de itens como cards clicáveis. Suporta seleção de item ativo, ícones Font Awesome e itens desabilitados.

## Quando usar

- Menus de navegação rápida em dashboards ou launchers de módulos
- Atalhos para ações frequentes dispostos em grade
- Menus onde o usuário precisa indicar qual módulo ou contexto está ativo (modo selecionável)

## Quando não usar

- Menus com hierarquia (submenus) — prefira [`TieredMenu`](../tiered-menu/README.md)
- Listas longas de itens com mais de uma coluna de informação — prefira uma tabela ou lista

## Instalação

```typescript
import { GridMenuModule } from '@seniorsistemas/angular-components/grid-menu';

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

## Uso básico

```html
<s-grid-menu [items]="menuItems" [useFontAwesomeIcons]="true" />
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `items` | `GridMenuItem \| GridMenuItem[]` | `[]` | Não | Lista de itens exibidos no grid. Valores nulos resultam em lista vazia. |
| `useFontAwesomeIcons` | `boolean` | `false` | Não | Quando `true`, o campo `icon` é tratado como classe Font Awesome. Quando `false`, como URL de imagem SVG. |
| `selectable` | `boolean` | `false` | Não | Habilita o modo de seleção. O item clicado fica marcado como ativo. |
| `selected` | `GridMenuItem` | — | Não | Item atualmente selecionado. Suporta two-way binding via `[(selected)]`. |

### Outputs

| Evento | Tipo | Descrição |
|--------|------|-----------|
| `selectedChange` | `EventEmitter<GridMenuItem>` | Emitido quando o usuário seleciona um novo item. Usado para two-way binding com `[(selected)]`. |

### Tipos

```typescript
type GridMenuItem = {
    icon?: string;                         // Classe FA (ex: 'fa-home') ou URL de imagem SVG
    label?: string;                        // Texto exibido abaixo do ícone
    action: () => void;                    // Função executada ao clicar (obrigatório)
    disabled?: boolean | (() => boolean);  // Desabilita o item
    active?: boolean;                      // Estado de seleção ativo (gerenciado internamente)
};
```

## Exemplos

### Menu básico com ícones Font Awesome

```html
<s-grid-menu
    [items]="items"
    [useFontAwesomeIcons]="true"
    [selectable]="false"
></s-grid-menu>
```

```typescript
items: GridMenuItem[] = [
    { icon: 'fa-home', label: 'Início', action: () => this.navegar('home') },
    { icon: 'fa-user', label: 'Perfil', action: () => this.navegar('perfil') },
    { icon: 'fa-cog', label: 'Configurações', action: () => this.navegar('config') },
];
```

### Menu com seleção e two-way binding

```html
<s-grid-menu
    [items]="items"
    [useFontAwesomeIcons]="true"
    [selectable]="true"
    [(selected)]="itemSelecionado"
    (selectedChange)="onItemSelecionado($event)"
></s-grid-menu>
<div>Selecionado: {{ itemSelecionado?.label }}</div>
```

### Menu com itens desabilitados

```html
<s-grid-menu
    [items]="itemsComDesabilitados"
    [useFontAwesomeIcons]="true"
></s-grid-menu>
```

```typescript
itemsComDesabilitados: GridMenuItem[] = [
    { icon: 'fa-home', label: 'Início', action: () => {} },
    { icon: 'fa-lock', label: 'Bloqueado', action: () => {}, disabled: true },
    { icon: 'fa-cog', label: 'Dinâmico', action: () => {}, disabled: () => !this.temPermissao },
];
```

## Acessibilidade

- Cada item do grid é um elemento clicável — utilize o `label` para descrição adequada
- Itens desabilitados bloqueiam interação e não emitem eventos
- O estado ativo (`active`) é visualmente distinguido para indicar a seleção atual

## Componentes relacionados

- [`TieredMenu`](../tiered-menu/README.md) — quando precisar de menus com hierarquia e submenus
- [`NavigationButton`](../navigation-button/README.md) — quando precisar de navegação sequencial entre etapas