# CalendarMask

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

Diretiva que aplica máscara de entrada ao componente `p-calendar` do PrimeNG, formatando automaticamente a data conforme o `dateFormat` configurado no calendário.

> **Nota:** Esta diretiva foi desenvolvida originalmente para PrimeNG v9. Em versões mais recentes (v18+), podem ocorrer incompatibilidades no ambiente Storybook, porém o uso em aplicações Angular reais continua funcionando normalmente.

## Quando usar

- Campos de data onde o usuário precisa digitar a data manualmente (em vez de selecionar no calendário)
- Formulários com `p-calendar` que exigem entrada por teclado formatada
- Quando é necessário suporte a máscaras em intervalos de datas (`selectionMode="range"`)

## Quando não usar

- Quando o usuário sempre selecionará a data pelo calendário gráfico — a máscara não é necessária
- Em novos campos de data com formatos muito diferentes de `dd/mm/yy` — teste a compatibilidade antes
- Com `p-calendar` em modo `inline` — a máscara destina-se ao input de texto

## Instalação

```typescript
import { CalendarMaskModule } from '@seniorsistemas/angular-components/calendar-mask';

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

## Uso básico

Adicione o atributo `sCalendarMask` diretamente ao `p-calendar`:

```html
<p-calendar sCalendarMask [(ngModel)]="data" dateFormat="dd/mm/yy" />
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `slotChar` | `string` | `'_'` | não | Caractere placeholder para posições não preenchidas na máscara |
| `autoClear` | `boolean` | `false` | não | Limpa o campo ao perder o foco se o valor for inválido |

## Exemplos

### Data simples

```html
<p-calendar sCalendarMask [(ngModel)]="data" dateFormat="dd/mm/yy" />
```

### Data e hora

```html
<p-calendar sCalendarMask [(ngModel)]="data" dateFormat="dd/mm/yy" [showTime]="true" />
```

### Data, hora e segundos

```html
<p-calendar sCalendarMask [(ngModel)]="data" dateFormat="dd/mm/yy" [showTime]="true" [showSeconds]="true" />
```

### Intervalo de datas

```html
<p-calendar sCalendarMask [(ngModel)]="data" dateFormat="dd/mm/yy" selectionMode="range" />
```

### Com limpeza automática de valor inválido

```html
<p-calendar sCalendarMask [autoClear]="true" [(ngModel)]="data" dateFormat="dd/mm/yy" />
```

## Acessibilidade

- A diretiva altera o `type` do input interno para `tel`, exibindo teclado numérico em dispositivos móveis
- A navegação por Tab é tratada pela diretiva para garantir o foco correto entre o input e o botão do calendário
- Use `aria-label` ou `<label for="...">` no `p-calendar` para associar corretamente o rótulo ao campo

## Componentes relacionados

- [`MaskFormatter`](../mask-formatter/README.md) — pipe de formatação de strings com máscara para exibição