# PasswordStrength

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

Diretiva Angular que adiciona um indicador visual de força de senha a qualquer campo de input. Ao receber foco ou a cada tecla digitada, exibe um popover com três barras coloridas e um título indicando o nível de força: fraca, média ou forte. Desaparece ao perder o foco.

## Quando usar

- Formulários de cadastro e alteração de senha onde o feedback de segurança é importante
- Qualquer campo de senha que precise orientar o usuário sobre a complexidade mínima exigida

## Quando não usar

- Para validação de senha no servidor — esta diretiva é apenas feedback visual no cliente
- Quando as regras de senha são exibidas de forma estática (lista de requisitos) — use texto informativo diretamente no formulário
- Em campos que não sejam de senha — use outros mecanismos de feedback

## Instalação

```typescript
import { PasswordStrengthModule } from '@seniorsistemas/angular-components/password-strength';

@NgModule({ imports: [PasswordStrengthModule] })
export class MeuModulo {}
```

## Uso básico

```html
<input
  type="password"
  [sPasswordStrength]="true"
  passwordStrengthDescription="A senha deve conter letras maiúsculas, números e caracteres especiais."
/>
```

## API

### Inputs (diretiva `sPasswordStrength`)

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `sPasswordStrength` | `boolean` | `true` | Não | Habilita ou desabilita o indicador de força |
| `passwordStrengthDescription` | `string` | — | Sim | Texto de orientação exibido no indicador |
| `passwordStrengthPosition` | `PasswordStrengthPositions` | `'right'` | Não | Posição preferencial do indicador em relação ao campo |
| `passwordStrengthWeakTitle` | `string` | Tradução padrão | Não | Texto customizado para o nível fraco |
| `passwordStrengthMediumTitle` | `string` | Tradução padrão | Não | Texto customizado para o nível médio |
| `passwordStrengthStrongTitle` | `string` | Tradução padrão | Não | Texto customizado para o nível forte |
| `passwordStrengthValidation` | `(content: string) => PasswordStrengths` | Validação padrão | Não | Função customizada para calcular a força da senha |

### Tipos

```typescript
type PasswordStrengthPositions = 'top' | 'right' | 'left';

type PasswordStrengths = 'veryWeak' | 'weak' | 'medium' | 'strong';
```

### Validação padrão

A função padrão avalia os seguintes critérios (1 ponto cada):

- Comprimento mínimo de 6 caracteres
- Contém pelo menos um número
- Contém pelo menos uma letra minúscula
- Contém pelo menos uma letra maiúscula
- Contém pelo menos um caractere especial (`!@#$%&*.\\=+^~-`)

| Pontos | Nível |
|--------|-------|
| 0 | `veryWeak` |
| 1–3 | `weak` |
| 4 | `medium` |
| 5 | `strong` |

## Exemplos

### Campo padrão com validação padrão

```html
<div style="display: flex; flex-direction: column; gap: 8px;">
  <label>Senha</label>
  <input
    type="password"
    [sPasswordStrength]="true"
    passwordStrengthDescription="A senha deve ter letras maiúsculas, números e caracteres especiais."
  />
</div>
```

### Com validação customizada

```html
<input
  type="password"
  [sPasswordStrength]="true"
  passwordStrengthDescription="A senha deve ter no mínimo 8 caracteres."
  [passwordStrengthValidation]="meuValidador"
/>
```

```typescript
meuValidador(content: string): PasswordStrengths {
  if (content.length < 4) return 'veryWeak';
  if (content.length < 6) return 'weak';
  if (content.length < 8) return 'medium';
  return 'strong';
}
```

### Com títulos customizados

```html
<input
  type="password"
  [sPasswordStrength]="true"
  passwordStrengthDescription="Use letras, números e símbolos."
  passwordStrengthWeakTitle="Insegura"
  passwordStrengthMediumTitle="Razoável"
  passwordStrengthStrongTitle="Segura"
/>
```

### Posicionado à esquerda

```html
<input
  type="password"
  [sPasswordStrength]="true"
  passwordStrengthDescription="Requisitos da senha."
  passwordStrengthPosition="left"
/>
```

## Acessibilidade

- O indicador é exibido ao focar o campo (`focus`) e a cada tecla digitada (`keyup`)
- O indicador desaparece ao perder o foco (`blur`)
- O componente reposiciona automaticamente entre `right`, `left` e `top` conforme o espaço disponível na viewport
- O texto de `passwordStrengthDescription` orienta o usuário sobre os requisitos da senha

## Componentes relacionados

- [`PinCodeField`](../pin-code-field/README.md) — campo de código PIN com navegação entre dígitos