@sysvale/ledi-fields-validator

Validador de campos de formulários HTML, com disparo automático de validação a partir de interações do usuário e injeção dinâmica de mensagens de erro no DOM.

Instalação

npm install @sysvale/ledi-fields-validator

ou

yarn add @sysvale/ledi-fields-validator

Visão geral de funcionamento

O fluxo de uso do validador é o seguinte:

1. O validador é instanciado passando-se um conjunto de configurações obrigatórias e opcionais.
2. Campos HTML que devem ser validados precisam conter atributos específicos (sysvale-data e sysvale-form).
3. A validação é disparada automaticamente no evento focusout desses campos.
4. Caso exista erro de validação, uma mensagem é injetada no DOM logo após o campo avaliado.
5. É obrigatório chamar o método abort() quando o validador não for mais necessário, garantindo a remoção correta dos event listeners.

Uso básico

Importação e instanciação

import LediValidator from '@sysvale/ledi-fields-validator';

const validator = new LediValidator({
  token: 'SEU_TOKEN_DE_AUTENTICACAO',
  recordVersion: '1.0.0',
  recordType: 'ficha-atendimento',
  context: {
    idade: 32,
    sexo: 'M',
  },
  dev: true,
});

Configuração

A instância do validador recebe um objeto de configuração com as seguintes propriedades:

token (obrigatório)

• Tipo: string
• Token utilizado para autenticação nas requisições ao servidor de validação.

recordVersion (obrigatório)

• Tipo: string
• Versão da ficha que será utilizada como base para a validação.

recordType (obrigatório)

• Tipo: string
• Identificador do tipo de ficha.
• Deve ser o mesmo valor informado no atributo sysvale-form dos campos HTML.

context (opcional)

• Tipo: Record<string, unknown>
• Objeto contendo dados adicionais necessários para a validação, mas que não fazem parte do formulário HTML.
• Exemplo de uso: informações derivadas de estado global da aplicação ou dados do usuário.

dev (opcional)

• Tipo: boolean
• Quando true, as requisições de validação são direcionadas para o servidor de desenvolvimento.
• Padrão: false

Marcação dos campos HTML

Para que um campo seja validado, ele obrigatoriamente deve conter os seguintes atributos:

sysvale-data

• Nome do campo conforme configurado no servidor de validação.

sysvale-form

• Nome da ficha à qual o campo pertence.
• Deve ser idêntico ao valor passado em recordType na configuração do validador.

Exemplo

<input
  type="text"
  name="cpf"
  sysvale-data="cpf"
  sysvale-form="ficha-atendimento"
/>

Disparo da validação

• A validação é automaticamente executada no evento focusout dos campos que atendem aos critérios descritos acima.
• Não é necessário chamar manualmente nenhuma função de validação.

Comportamento em caso de erro

• Se a validação não encontrar problemas, nenhuma ação visual ocorre.

• Se for identificado um erro:

  • Um elemento contendo a mensagem de erro é injetado no DOM.
  • Esse elemento é inserido logo após o campo que falhou na validação.
  • A mensagem exibida corresponde exatamente ao erro retornado pelo servidor de validação.

Finalização e limpeza (obrigatório)

Após o uso do validador — por exemplo, ao desmontar uma página, trocar de rota ou destruir um componente — é imprescindível chamar o método abort().

Isso garante que todos os event listeners adicionados durante a instanciação sejam corretamente removidos, evitando vazamentos de memória e comportamentos inesperados.

Exemplo

LediValidator().abort();

Atenção: não chamar abort() pode resultar em múltiplos listeners sendo registrados para os mesmos campos ao longo do ciclo de vida da aplicação.

Compatibilidade

• Projetado para uso em aplicações frontend baseadas em JavaScript ou TypeScript.
• Funciona com formulários HTML nativos.
• Compatível com SPAs (React, Vue, Angular, etc.), desde que o ciclo de vida do validador seja corretamente gerenciado.