pjc-fields 0.0.44 → 0.0.46

package/README.md

@@ -1,64 +1,613 @@
-# PjcFields
+# pjc-fields
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 21.2.0.
+Biblioteca Angular de campos de formulário para dados tipicamente brasileiros — CPF, CNPJ, telefone, placa, data, hora, CEP, CNH, RENAVAM, chassi, IMEI, cartão, moeda e muito mais. Construída sobre [PrimeNG](https://primeng.org/) com suporte completo a Reactive Forms via `ControlValueAccessor` e `Validator`.
 
-## Code scaffolding
+- **Demo:** https://pjcfields.alvarocda.dev/
+- **NPM:** https://www.npmjs.com/package/pjc-fields
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+
+---
+
+## Instalação
 
 ```bash
-ng generate component component-name
+npm install pjc-fields
 ```
 
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+### Dependências necessárias (peer dependencies)
 
-```bash
-ng generate --help
+| Pacote | Versão |
+|---|---|
+| `@angular/common` | `^21.2.0` |
+| `@angular/core` | `^21.2.0` |
+| `@angular/forms` | `^21.2.0` |
+| `primeng` | `^21.1.3` |
+| `@primeuix/themes` | `^2.0.3` |
+| `primeicons` | `^7.0.0` |
+
+---
+
+## Uso básico
+
+Todos os componentes são **standalone** — importe diretamente no array `imports` do seu componente Angular:
+
+```typescript
+import { PjcCpfFieldComponent } from 'pjc-fields';
+
+@Component({
+  imports: [ReactiveFormsModule, PjcCpfFieldComponent],
+})
+export class MeuComponent {
+  form = new FormGroup({
+    cpf: new FormControl(''),
+  });
+}
+```
+
+```html
+<form [formGroup]="form">
+  <pjc-cpf-field formControlName="cpf" label="CPF" />
+</form>
 ```
 
-## Building
+---
 
-To build the library, run:
+## Componentes
 
-```bash
-ng build pjc-fields
+### `pjc-cpf-field`
+
+Campo de CPF com máscara `000.000.000-00` e validação pelo algoritmo Módulo 11.
+
+```html
+<pjc-cpf-field
+  formControlName="cpf"
+  label="CPF"
+  placeholder="000.000.000-00"
+  labelVariant="over"
+/>
 ```
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+| Input | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `label` | `string` | `''` | Rótulo do campo |
+| `hint` | `string` | `''` | Texto de dica abaixo do campo |
+| `placeholder` | `string` | `000.000.000-00` | Placeholder |
+| `id` | `string` | gerado automaticamente | ID do elemento |
+| `labelVariant` | `'over' \| 'in' \| 'on'` | `'over'` | Variante do FloatLabel do PrimeNG |
+| `readonly` | `boolean` | `false` | Impede edição sem desabilitar o controle |
+| `erros` | `Record<string, string>` | `{}` | Mapa de chave de erro → mensagem |
 
-### Publishing the Library
+Erro de validação: `cpfInvalido`
 
-Once the project is built, you can publish your library by following these steps:
+---
 
-1. Navigate to the `dist` directory:
+### `pjc-cnpj-field`
 
-   ```bash
-   cd dist/pjc-fields
-   ```
+Campo de CNPJ com máscara `00.000.000/0000-00` e validação pelo algoritmo Módulo 11.
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+```html
+<pjc-cnpj-field
+  formControlName="cnpj"
+  label="CNPJ"
+/>
+```
 
-## Running unit tests
+Mesmos inputs de `pjc-cpf-field`. Erro de validação: `cnpjInvalido`
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+---
 
-```bash
-ng test
+### `pjc-cpf-cnpj-field`
+
+Campo que aceita CPF **ou** CNPJ com máscara dinâmica — alterna automaticamente conforme o tamanho digitado.
+
+```html
+<pjc-cpf-cnpj-field
+  formControlName="documento"
+  label="CPF / CNPJ"
+/>
+```
+
+Erros de validação: `cpfInvalido` ou `cnpjInvalido`
+
+---
+
+### `pjc-telefone-field`
+
+Campo de telefone com suporte a fixo (10 dígitos) e celular (11 dígitos, com 9 após o DDD).
+
+```html
+<pjc-telefone-field
+  formControlName="telefone"
+  label="Telefone"
+/>
+```
+
+Erro de validação: `telefoneInvalido`
+
+---
+
+### `pjc-placa-field`
+
+Campo de placa de veículo com suporte ao padrão antigo (`AAA9999`) e Mercosul (`AAA9A99`).
+
+```html
+<pjc-placa-field
+  formControlName="placa"
+  label="Placa do Veículo"
+/>
+```
+
+Erro de validação: `placaInvalida`
+
+---
+
+### `pjc-data-field`
+
+Campo de data com PrimeNG DatePicker. O valor do controle é `Date | null`. Suporta `minDate` e `maxDate`.
+
+```html
+<pjc-data-field
+  formControlName="dataNascimento"
+  label="Data de Nascimento"
+  [minDate]="minDate"
+  [maxDate]="maxDate"
+/>
+```
+
+| Input | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `label` | `string` | `'Data'` | Rótulo do campo |
+| `id` | `string` | gerado automaticamente | ID do elemento |
+| `minDate` | `Date \| undefined` | `undefined` | Data mínima selecionável |
+| `maxDate` | `Date \| undefined` | `undefined` | Data máxima selecionável |
+| `labelVariant` | `'over' \| 'in' \| 'on'` | `'on'` | Variante do FloatLabel |
+| `readonly` | `boolean` | `false` | Impede edição sem desabilitar o controle |
+| `erros` | `Record<string, string>` | `{}` | Mapa de chave de erro → mensagem |
+
+Erros de validação: `dataMinima`, `dataMaxima`
+
+---
+
+### `pjc-data-hora-field`
+
+Campo de data **e hora** com PrimeNG DatePicker (`showTime`). O valor do controle é `Date | null`.
+
+```html
+<pjc-data-hora-field
+  formControlName="dataHora"
+  label="Data e Hora"
+  [minDate]="minDate"
+  [maxDate]="maxDate"
+/>
+```
+
+Mesmos inputs de `pjc-data-field`. Erros de validação: `dataMinima`, `dataMaxima`
+
+---
+
+### `pjc-hora-field`
+
+Campo de hora com máscara `HH:MM` e validação de intervalo (00:00–23:59).
+
+```html
+<pjc-hora-field
+  formControlName="horario"
+  label="Horário"
+/>
+```
+
+Erro de validação: `horaInvalida`
+
+---
+
+### `pjc-cep-field`
+
+Campo de CEP com máscara `99999-999`. O valor do controle são os 8 dígitos sem formatação. Inclui botão de busca opcional e evento `busca` para disparar consulta de endereço.
+
+```html
+<pjc-cep-field
+  formControlName="cep"
+  label="CEP"
+  (busca)="onBusca($event)"
+  [erros]="{ required: 'CEP obrigatório.', cepInvalido: 'CEP inválido.' }"
+/>
+```
+
+| Input | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `label` | `string` | `''` | Rótulo do campo |
+| `hint` | `string` | `''` | Texto de dica abaixo do campo |
+| `placeholder` | `string` | `'00000-000'` | Placeholder |
+| `id` | `string` | gerado automaticamente | ID do elemento |
+| `labelVariant` | `'over' \| 'in' \| 'on'` | `'on'` | Variante do FloatLabel |
+| `readonly` | `boolean` | `false` | Impede edição sem desabilitar o controle |
+| `showSearchButton` | `boolean` | `true` | Exibe botão de busca ao lado do campo |
+| `erros` | `Record<string, string>` | `{}` | Mapa de chave de erro → mensagem |
+
+| Output | Tipo | Descrição |
+|---|---|---|
+| `busca` | `string` | Emite os 8 dígitos brutos ao completar a máscara ou clicar no botão de busca |
+
+Erro de validação: `cepInvalido`
+
+---
+
+### `pjc-cnh-field`
+
+Campo de CNH com validação Módulo 11.
+
+```html
+<pjc-cnh-field
+  formControlName="cnh"
+  label="CNH"
+/>
+```
+
+Erro de validação: `cnhInvalida`
+
+---
+
+### `pjc-renavam-field`
+
+Campo de RENAVAM com validação Módulo 11.
+
+```html
+<pjc-renavam-field
+  formControlName="renavam"
+  label="RENAVAM"
+/>
 ```
 
-## Running end-to-end tests
+Erro de validação: `renavamInvalido`
 
-For end-to-end (e2e) testing, run:
+---
+
+### `pjc-chassi-field`
+
+Campo de chassi/VIN (17 caracteres, alfabeto VIN).
+
+```html
+<pjc-chassi-field
+  formControlName="chassi"
+  label="Chassi"
+/>
+```
+
+Erro de validação: `chassiInvalido`
+
+---
+
+### `pjc-imei-field`
+
+Campo de IMEI com validação Luhn (15 dígitos).
+
+```html
+<pjc-imei-field
+  formControlName="imei"
+  label="IMEI"
+/>
+```
+
+Erro de validação: `imeiInvalido`
+
+---
+
+### `pjc-numero-cartao-field`
+
+Campo de número de cartão com validação Luhn (13–19 dígitos).
+
+```html
+<pjc-numero-cartao-field
+  formControlName="numeroCartao"
+  label="Número do Cartão"
+/>
+```
+
+Erro de validação: `numeroCartaoInvalido`
+
+---
+
+### `pjc-email-field`
+
+Campo de e-mail que converte automaticamente a entrada para minúsculas.
+
+```html
+<pjc-email-field
+  formControlName="email"
+  label="E-mail"
+/>
+```
+
+Erro de validação: `emailInvalido`
+
+---
+
+### `pjc-uppercase-field`
+
+Campo de texto com conversão automática para maiúsculas. Ideal para nomes e razão social.
+
+```html
+<pjc-uppercase-field
+  formControlName="nome"
+  label="Nome Completo"
+  placeholder="Digite o nome"
+/>
+```
+
+Sem validação própria — sem erro de validação.
+
+---
+
+### `pjc-password-field`
+
+Campo de senha com botão de mostrar/ocultar.
+
+```html
+<pjc-password-field
+  formControlName="senha"
+  label="Senha"
+/>
+```
+
+Sem validação própria — use `Validators.minLength` etc. no `FormControl`.
+
+---
+
+### `pjc-moeda-field`
+
+Campo de moeda/decimal com acumulação de centavos por teclado (estilo caixa registradora). O valor do controle é `number | null` (`null` quando zero).
+
+```html
+<pjc-moeda-field
+  formControlName="valor"
+  label="Valor"
+  mode="currency"
+  currency="BRL"
+/>
+```
+
+| Input | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `label` | `string` | `''` | Rótulo do campo |
+| `hint` | `string` | `''` | Texto de dica |
+| `id` | `string` | gerado automaticamente | ID do elemento |
+| `labelVariant` | `'over' \| 'in' \| 'on'` | `'on'` | Variante do FloatLabel |
+| `mode` | `'currency' \| 'decimal'` | `'currency'` | Modo de exibição |
+| `currency` | `string` | `'BRL'` | Código ISO 4217 da moeda |
+| `locale` | `string` | `'pt-BR'` | Locale para `Intl.NumberFormat` |
+| `minFractionDigits` | `number` | `2` | Casas decimais mínimas |
+| `maxFractionDigits` | `number` | `2` | Casas decimais máximas |
+| `readonly` | `boolean` | `false` | Impede entrada sem desabilitar o controle |
+| `erros` | `Record<string, string>` | `{}` | Mapa de chave de erro → mensagem |
+
+Sem validação própria — use `PjcValidators.decimalMaiorZero()` no `FormControl`.
+
+---
+
+### `pjc-integer-field`
+
+Campo numérico inteiro (PrimeNG InputNumber com `maxFractionDigits=0`).
+
+```html
+<pjc-integer-field
+  formControlName="quantidade"
+  label="Quantidade"
+/>
+```
+
+Sem validação própria — use `PjcValidators.inteiroMaiorZero()` no `FormControl`.
+
+---
+
+### `pjc-tipo-pessoa-field`
+
+Dropdown para tipo de pessoa: `FISICA` ou `JURIDICA`.
+
+```html
+<pjc-tipo-pessoa-field
+  formControlName="tipoPessoa"
+  label="Tipo de Pessoa"
+/>
+```
+
+Sem validação própria.
+
+---
+
+### `pjc-uf-field`
+
+Dropdown com todas as 27 UFs brasileiras.
+
+```html
+<pjc-uf-field
+  formControlName="uf"
+  label="Estado"
+/>
+```
+
+Sem validação própria.
+
+---
+
+### `pjc-cidade-field`
+
+Autocomplete de município via API do IBGE, filtrável pela UF selecionada.
+
+```html
+<pjc-cidade-field
+  formControlName="cidade"
+  label="Município"
+  [uf]="form.get('uf')?.value"
+/>
+```
+
+Sem validação própria.
+
+---
+
+### `pjc-erro-validacao`
+
+Componente utilitário que exibe mensagens de erro de validação para um `FormControl` pelo nome dentro de um `FormGroup`. **Não é um campo de formulário** — não implementa `ControlValueAccessor`.
+
+```html
+<form [formGroup]="form">
+  <pjc-cpf-field formControlName="cpf" label="CPF" />
+  <pjc-erro-validacao
+    controlName="cpf"
+    [erros]="{ required: 'CPF obrigatório.', cpfInvalido: 'CPF inválido.' }"
+  />
+</form>
+```
+
+| Input | Tipo | Obrigatório | Descrição |
+|---|---|---|---|
+| `controlName` | `string` | Sim | Nome do controle no `FormGroup` |
+| `erros` | `Record<string, string>` | Sim | Mapa de chave de erro → mensagem |
+
+> **Nota:** não use `[erros]` no próprio campo **e** `pjc-erro-validacao` ao mesmo tempo para o mesmo controle — as mensagens serão duplicadas.
+
+---
+
+## Validadores standalone (`PjcValidators`)
+
+Use os validadores de forma independente, sem os componentes, em qualquer `FormControl`.
+
+> **Atenção:** os componentes `pjc-*-field` que validam já se registram como `NG_VALIDATORS`. **Não adicione** o `PjcValidators` correspondente ao mesmo `FormControl` — os erros serão duplicados.
+
+```typescript
+import { PjcValidators } from 'pjc-fields';
+
+form = new FormGroup({
+  cpf:        new FormControl('', [PjcValidators.cpf()]),
+  cnpj:       new FormControl('', [PjcValidators.cnpj()]),
+  doc:        new FormControl('', [PjcValidators.cpfCnpj()]),
+  telefone:   new FormControl('', [PjcValidators.telefone()]),
+  hora:       new FormControl('', [PjcValidators.hora()]),
+  placa:      new FormControl('', [PjcValidators.placaVeiculo()]),
+  email:      new FormControl('', [PjcValidators.email()]),
+  imei:       new FormControl('', [PjcValidators.imei()]),
+  cartao:     new FormControl('', [PjcValidators.numeroCartao()]),
+  renavam:    new FormControl('', [PjcValidators.renavam()]),
+  chassi:     new FormControl('', [PjcValidators.chassi()]),
+  cnh:        new FormControl('', [PjcValidators.cnh()]),
+  cep:        new FormControl('', [PjcValidators.cep()]),
+});
+```
+
+### Validadores de domínio
+
+| Método | Erro retornado |
+|---|---|
+| `PjcValidators.cpf()` | `{ cpfInvalido: true }` |
+| `PjcValidators.cnpj()` | `{ cnpjInvalido: true }` |
+| `PjcValidators.cpfCnpj()` | `{ cpfInvalido: true }` ou `{ cnpjInvalido: true }` |
+| `PjcValidators.telefone()` | `{ telefoneInvalido: true }` |
+| `PjcValidators.hora()` | `{ horaInvalida: true }` |
+| `PjcValidators.placaVeiculo()` | `{ placaInvalida: true }` |
+| `PjcValidators.email()` | `{ emailInvalido: true }` |
+| `PjcValidators.imei()` | `{ imeiInvalido: true }` |
+| `PjcValidators.numeroCartao()` | `{ numeroCartaoInvalido: true }` |
+| `PjcValidators.renavam()` | `{ renavamInvalido: true }` |
+| `PjcValidators.chassi()` | `{ chassiInvalido: true }` |
+| `PjcValidators.cnh()` | `{ cnhInvalida: true }` |
+| `PjcValidators.cep()` | `{ cepInvalido: true }` |
+
+### Validadores numéricos
+
+Use com `pjc-integer-field`, `pjc-moeda-field` ou `<input type="number">`.
+
+#### Inteiros
+
+| Método | Erro retornado | Condição |
+|---|---|---|
+| `PjcValidators.inteiroMaiorZero()` | `{ inteiroMaiorZero: true }` | `value ≤ 0` |
+| `PjcValidators.inteiroMaiorIgualZero()` | `{ inteiroMaiorIgualZero: true }` | `value < 0` |
+| `PjcValidators.inteiroMenorZero()` | `{ inteiroMenorZero: true }` | `value ≥ 0` |
+| `PjcValidators.inteiroMenorIgualZero()` | `{ inteiroMenorIgualZero: true }` | `value > 0` |
+| `PjcValidators.inteiroNuloOuMaiorZero()` | `{ inteiroNuloOuMaiorZero: true }` | `value ≤ 0` (null permitido) |
+| `PjcValidators.inteiroNuloOuMaiorIgualZero()` | `{ inteiroNuloOuMaiorIgualZero: true }` | `value < 0` (null permitido) |
+| `PjcValidators.inteiroNuloOuMenorZero()` | `{ inteiroNuloOuMenorZero: true }` | `value ≥ 0` (null permitido) |
+| `PjcValidators.inteiroNuloOuMenorIgualZero()` | `{ inteiroNuloOuMenorIgualZero: true }` | `value > 0` (null permitido) |
+
+#### Decimais
+
+| Método | Erro retornado | Condição |
+|---|---|---|
+| `PjcValidators.decimalMaiorZero()` | `{ decimalMaiorZero: true }` | `value ≤ 0` |
+| `PjcValidators.decimalMaiorIgualZero()` | `{ decimalMaiorIgualZero: true }` | `value < 0` |
+| `PjcValidators.decimalMenorZero()` | `{ decimalMenorZero: true }` | `value ≥ 0` |
+| `PjcValidators.decimalMenorIgualZero()` | `{ decimalMenorIgualZero: true }` | `value > 0` |
+
+---
+
+## Exibindo erros de validação
+
+### Via input `erros` no próprio campo
+
+```html
+<pjc-cpf-field
+  formControlName="cpf"
+  label="CPF"
+  [erros]="{ required: 'CPF obrigatório.', cpfInvalido: 'CPF inválido.' }"
+/>
+```
+
+### Via `pjc-erro-validacao`
+
+```html
+<pjc-cpf-field formControlName="cpf" label="CPF" />
+<pjc-erro-validacao
+  controlName="cpf"
+  [erros]="{ required: 'CPF obrigatório.', cpfInvalido: 'CPF inválido.' }"
+/>
+```
+
+### Via template manual
+
+```html
+<pjc-cpf-field formControlName="cpf" label="CPF" />
+@if (form.get('cpf')?.hasError('cpfInvalido') && form.get('cpf')?.touched) {
+  <small class="p-error">CPF inválido.</small>
+}
+```
+
+---
+
+## Documentação para IA (llms.txt)
+
+Este repositório inclui documentação no formato AI-ready:
+
+- **[llms.txt](llms.txt)** — índice de todos os arquivos de documentação da biblioteca, seguindo o padrão [llms.txt](https://llmstxt.org/).
+- **[docs/kb/](docs/kb/)** — documentação detalhada de cada componente e validador em Markdown, pronta para uso com Claude Projects, Cursor, GitHub Copilot e similares.
+
+Para usar com seu assistente de IA:
+
+1. Aponte seu assistente para o arquivo `llms.txt` do repositório, ou
+2. Cole o conteúdo de `docs/kb/index.md` no contexto do seu projeto.
+
+---
+
+## Desenvolvimento local
 
 ```bash
-ng e2e
+# Instalar dependências
+npm install
+
+# Servidor de desenvolvimento (porta 4200)
+npm start
+
+# Executar todos os testes
+npm test
+
+# Executar testes apenas da biblioteca
+ng test pjc-fields
+
+# Reconstruir a biblioteca e iniciar o demo
+ng build pjc-fields && npm start
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+---
 
-## Additional Resources
+## Licença
 
-For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+MIT