pjc-fields

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 com suporte completo a Reactive Forms via ControlValueAccessor e Validator.

• Demo: https://pjcfields.alvarocda.dev/
• NPM: https://www.npmjs.com/package/pjc-fields

Instalação

npm install pjc-fields

Dependências necessárias (peer dependencies)

| 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:

import { PjcCpfFieldComponent } from 'pjc-fields';

@Component({
  imports: [ReactiveFormsModule, PjcCpfFieldComponent],
})
export class MeuComponent {
  form = new FormGroup({
    cpf: new FormControl(''),
  });
}

<form [formGroup]="form">
  <pjc-cpf-field formControlName="cpf" label="CPF" />
</form>

Componentes

pjc-cpf-field

Campo de CPF com máscara 000.000.000-00 e validação pelo algoritmo Módulo 11.

<pjc-cpf-field
  formControlName="cpf"
  label="CPF"
  placeholder="000.000.000-00"
  labelVariant="over"
/>

| 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 |

Erro de validação: cpfInvalido

pjc-cnpj-field

Campo de CNPJ com máscara 00.000.000/0000-00 e validação pelo algoritmo Módulo 11.

<pjc-cnpj-field
  formControlName="cnpj"
  label="CNPJ"
/>

Mesmos inputs de pjc-cpf-field. Erro de validação: cnpjInvalido

pjc-cpf-cnpj-field

Campo que aceita CPF ou CNPJ com máscara dinâmica — alterna automaticamente conforme o tamanho digitado.

<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).

<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).

<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.

<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.

<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).

<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.

<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.

<pjc-cnh-field
  formControlName="cnh"
  label="CNH"
/>

Erro de validação: cnhInvalida

pjc-renavam-field

Campo de RENAVAM com validação Módulo 11.

<pjc-renavam-field
  formControlName="renavam"
  label="RENAVAM"
/>

Erro de validação: renavamInvalido

pjc-chassi-field

Campo de chassi/VIN (17 caracteres, alfabeto VIN).

<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).

<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).

<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.

<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.

<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.

<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).

<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).

<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.

<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.

<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.

<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.

<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.

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

<pjc-cpf-field
  formControlName="cpf"
  label="CPF"
  [erros]="{ required: 'CPF obrigatório.', cpfInvalido: 'CPF inválido.' }"
/>

Via pjc-erro-validacao

<pjc-cpf-field formControlName="cpf" label="CPF" />
<pjc-erro-validacao
  controlName="cpf"
  [erros]="{ required: 'CPF obrigatório.', cpfInvalido: 'CPF inválido.' }"
/>

Via template manual

<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 — índice de todos os arquivos de documentação da biblioteca, seguindo o padrão llms.txt.
• 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

# 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

Licença

MIT