@kenero/use-validate

Validação simples, máscaras em tempo real e exibição de erros para formulários React — com uma API minimalista e tipada.

> Stack: React + TypeScript
>
> Use cases: checkouts, cadastros, pagamentos, formulários com muitos inputs.

---

🚀 Instalação

``bash
npm i @kenero/use-validate

ou

yarn add @kenero/use-validate
`

---

⚡️ Comece rápido

`tsx
import { ValidationProvider, useValidation } from "@kenero/use-validate";

export default function App() {
return (



);
}

function CheckoutForm() {
const { register, trigger, errors, resetErros } = useValidation();

const onSubmit = (e: React.FormEvent) => {
e.preventDefault();
if (trigger()) {
// Envie os dados com segurança
console.log("Form válido!");
}
};

return (

{/ CPF com máscara + required /}
{...register("cpf", () => {}, { required: true, mask: "cpf" })}
placeholder="CPF"
/>
{errors?.cpf?.error && {errors.cpf.message}}

{/ Telefone com máscara /}
{...register("phone", () => {}, { mask: "phone" })}
placeholder="Telefone"
/>
{errors?.phone?.error && {errors.phone.message}}

Enviar
resetErros()}>Limpar erros

);
}
`

---

🧠 Conceitos

* ValidationProvider: provê o contexto de validação e máscaras.
* useValidation(): acessa a API do formulário atual.
* register(id, onChange, options): conecta qualquer ou .

* Retorna { ref, onBlur, onChange } para plugar diretamente no elemento.
* trigger(keys?): valida todos os campos (ou apenas os informados).
* resetErros(keys?): limpa erros globalmente (ou seletivamente).
* errors: dicionário { [id]: { error: boolean; message: string } }.

---

📦 API (Tipos)

`ts
interface ErrosValidation {
[key: string]: { error: boolean; message: string } | undefined | null;
}

interface Options {
cpf?: boolean; // valida padrão CPF
cnpj?: boolean; // valida padrão CNPJ
nameAndLastName?: boolean; // exige nome e sobrenome
required?: boolean; // campo obrigatório
nameOptional?: string; // nome legível do campo para mensagens
minLength?: number; // tamanho mínimo
mask?:
| "cpf"
| "phone"
| "card-number"
| "card-data"
| "name"
| "cpf-cnpj"
| "cnpj"
| "plate"
| "chassi"
| "cep";
}

type TypeRegister = (
id: string,
onChange: (e: React.ChangeEvent) => void,
options?: Options
) => {
ref: React.RefObject;
onBlur: (e: React.ChangeEvent) => void;
onChange: (e: React.ChangeEvent) => void;
};
`

$3

`ts
declare const ValidationContext: React.Context;

declare const ValidationProvider: React.ForwardRefExoticComponent<
(ValidationProviderProps | ValidationProviderElementProps) &
React.RefAttributes
>;

declare const useValidation: () => ValidationContext;
`

---



🧩 ValidationProvider — duas formas de usar

$3

`tsx



`

$3

`tsx

{(ctx) => }

`

Use o formato que preferir — ambos expõem a mesma API por useValidation() ou pelo parâmetro ctx.

---



🧰 register em detalhe



`tsx
{...register(
"email",
(e) => {
// Seu estado/controlador também recebe o onChange
// Ex: setEmail(e.target.value)
},
{ required: true, minLength: 5, nameOptional: "E-mail" }
)}
placeholder="E-mail"
/>
{errors?.email?.error && {errors.email.message}}
`

O que acontece por baixo:

* Aplica máscara (se houver) a cada onChange.
* Executa validações declarativas conforme options.
* Em onBlur, revalida e atualiza errors[id].

> Dica: se você já controla o estado do campo (controlled input), continue usando seu setState dentro do onChange que você passa para o register.

---



🧪 trigger e resetErros



`ts
trigger(); // valida tudo
trigger(["cpf"]); // valida só alguns campos
resetErros(); // limpa todos os erros
resetErros(["cpf"]);// limpa erros selecionados
`

trigger() retorna true se todos os campos validados estiverem ok.

---

🔤 Máscaras disponíveis

| Máscara | ID em mask | Comportamento (exemplo) |
| ----------- | --------------- | ---------------------------------- |
| CPF | "cpf" | 123.456.789-09 |
| CNPJ | "cnpj" | 12.345.678/0001-90 |
| CPF ou CNPJ | "cpf-cnpj" | Detecta pelo tamanho e formata |
| Telefone | "phone" | () -* (dinâmico) |
| Cartão nº | "card-number" | #### #### #### #### |
| Cartão data | "card-data" | MM/AA |
| Nome | "name" | Remove números/sinais; capitaliza |
| Placa | "plate" | Padrão brasileiro (ex.: ABC1D23) |
| Chassi | "chassi" | Limita e normaliza alfanumérico |
| CEP | "cep" | #####-### |

> A máscara é aplicada durante o onChange. Em onBlur, a validação final ajusta mensagens de erro se necessário.

---

✅ Regras de validação prontas

* required: não permite vazio.
* minLength: impõe tamanho mínimo.
* cpf: valida estrutura/dígitos do CPF.
* cnpj: valida estrutura/dígitos do CNPJ.
* nameAndLastName: exige ao menos duas palavras válidas.
* nameOptional: rótulo amigável usado em mensagens (ex.: "O campo E-mail é obrigatório").

> Combine regras livremente com qualquer máscara.

---

🧩 Exemplos práticos

$3

`tsx
{...register("cpf", () => {}, { required: true, mask: "cpf", nameOptional: "CPF" })}
placeholder="CPF"
/>
{errors?.cpf?.error && {errors.cpf.message}}
`

$3

`tsx
{...register("nome", () => {}, { nameAndLastName: true, mask: "name", required: true })}
placeholder="Nome completo"
/>
`

$3

`tsx
{...register("phone", () => {}, { mask: "phone", required: true })}
placeholder="(00) 0 0000-0000"
/>
`

$3

`tsx
{...register("cep", () => {}, { mask: "cep", required: true })}
placeholder="00000-000"
onBlur={(e) => {
// opcional: fetch do endereço pelo CEP limpo
}}
/>
`

$3

`tsx
{...register("uf", () => {}, { required: true, nameOptional: "Estado" })}
defaultValue=""
>
Selecione
SP
RJ

{errors?.uf?.error && {errors.uf.message}}
`

---

♿ Acessibilidade

* Exiba mensagens de erro com role="alert" quando aplicável.
* Associe label/htmlFor e id de cada campo registrado.
* Use aria-invalid={errors?.[id]?.error || false} nos inputs para sinalizar estado.

---

🧪 Padrões de uso (UI libs)

$3

`tsx
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";

function FieldCPF() {
const { register, errors } = useValidation();

return (

CPF
{}, { mask: "cpf", required: true })} />
{errors?.cpf?.error && (

{errors.cpf.message}

)}

);
}
`

---

🧩 Dicas & Boas práticas

* IDs únicos: o primeiro parâmetro do register é a chave em errors — mantenha-o estável.
* onBlur remove erros: quando o campo volta a ficar válido, o erro correspondente é limpo automaticamente ao perder o foco.
* Controlled inputs: continue controlando seu estado normal; o register apenas adiciona máscara/validação.
* Validação seletiva: use trigger(["campo1", "campo2"]) em etapas do formulário.

---

❓FAQ

Preciso usar useState para todos os campos?
Não é obrigatório. O register já aplica máscara/validação. Use estado próprio se precisar ler valores no ato.

Consigo validar apenas uma parte do formulário?
Sim, passe as chaves para trigger(["cpf", "cep"]).

Como limpo mensagens de erro após corrigir o valor?
Erros são atualizados em onBlur. Para limpar globalmente, use resetErros(); para casos específicos, resetErros(["id"]).

---

🔌 API Completa (Resumo)

$3

* Aceita children como nós React ou como função (ctx) => JSX.

$3

* register: TypeRegister
* trigger(keys?: string[]): boolean
* resetErros(keys?: string[]): void
* errors: ErrosValidation

$3

* Parâmetros: (id, onChange, options?)
* Retorno: { ref, onBlur, onChange }`

---

🗺️ Roadmap

* Mensagens de erro totalmente customizáveis por regra.
* Hooks utilitários para extrair valores mascarados/limpos.
* Suporte a mais máscaras nacionais.

---

📄 Licença

MIT