feat: adiciona máscaras de input e suporte a CNPJ alfanumérico

[FabioRolin]

Tipo de mudança

feature

Contexto

Atualmente 34 MFEs do ecossistema mantêm cópias quase idênticas de src/utils/masks.ts/masks.js baseadas em vanilla-masker, gerando manutenção pulverizada. Além disso, a Receita Federal está adotando o CNPJ alfanumérico (Nota Técnica RFB NT 49/2024) — letras A-Z nas 12 primeiras posições + 2 dígitos verificadores numéricos —, e as funções atuais de formatCnpj, normalizeCpfOrCnpj e isCnpj no blu-utils usam replace(/\D/g, '')/regex puramente numérica, destruindo silenciosamente as letras.

Esta PR é a Fase 1 descrita no PRD: centralizar todas as máscaras de input no @useblu/utils (já re-exportado pelo mfe-core como core/blu-utils via Module Federation) e atualizar as funções existentes para suportarem o novo formato. A Fase 2 (migração dos 34 MFEs para consumirem core/blu-utils em vez dos arquivos locais) ficará para depois.

Solução

Novo módulo src/masks/

Reúne em um lugar único: maskValue, maskInput, maskCpf, maskCpfOrCnpj, maskComplete, setupMultipleMask, maskHintBankAccount.

• Engine de máscara: vanilla-masker (adicionado como dependency) — placeholders 9 (dígito), S (alfanumérico), A (letra). CNPJ usa pattern SS.SSS.SSS/SSSS-99 (12 alfa + 2 dígito).
• Validação de CNPJ: isCnpj.ts virou wrapper sobre cpf-cnpj-validator@2.1.0 (cnpj.isValid(value.toUpperCase())), que já implementa o algoritmo de DV alfanumérico oficial e mantém blacklist de CNPJs inválidos. A blacklist e o verifierDigit locais foram removidos (a lib cuida).
• Normalização: todo CNPJ é normalizado para .toUpperCase() no ponto de entrada via helper stripAlphanumeric (regex /[^A-Za-z0-9]/g + uppercase). Helpers de strip centralizados em src/masks/strip.ts para evitar duplicação de regex em 6+ arquivos.

API pública enxuta

Após análise de uso real nos MFEs, não foram expostos: masks (constante), cnpjMask, cpfMask, bankAccountMasks, maskBankAccount. A constante interna foi renomeada masks → MASKS com chaves UPPERCASE para deixar claro que é detalhe de implementação.

Retrocompatibilidade

• formatCnpj, normalizeCpfOrCnpj e isCnpj mantêm a mesma assinatura. CNPJ numérico continua funcionando exatamente como antes (cobertura via testes de regressão).
• O parâmetro strict de isCnpj perde efeito prático (a cpf-cnpj-validator aceita ambos os formatos). Marcado como @deprecated no JSDoc.

Principais mudanças

• Novo módulo src/masks/ com 9 arquivos (types.ts, masks.ts, strip.ts, maskValue.ts, maskInput.ts, maskCpf.ts, maskCpfOrCnpj.ts, maskComplete.ts, setupMultipleMask.ts, maskHintBankAccount.ts, vanilla-masker.d.ts)
• src/formatters/formatCnpj.ts reescrito para usar stripAlphanumeric + VMasker.toPattern(stripped, MASKS.CNPJ)
• src/normalizers/normalizeCpfOrCnpj.ts atualizado para CNPJ alfanumérico (>11 chars limpos)
• src/validations/isCnpj.ts virou wrapper de 4 linhas sobre cpf-cnpj-validator
• src/index.ts adiciona bloco // masks com 7 funções e 3 types públicos
• package.json: vanilla-masker@^1.2.0 e cpf-cnpj-validator@2.1.0 em dependencies; jest-environment-jsdom@29 em devDependencies (necessário para testes do maskInput)
• 8 arquivos de teste novos em tests/masks/ + tests/formatCnpj.spec.ts; tests/isCnpj.spec.ts e tests/normalizeCpfOrCnpj.spec.ts estendidos com casos de CNPJ alfanumérico

Impacto

• Escopo: apenas o pacote @useblu/utils. Nenhum MFE é afetado nesta entrega — a migração para core/blu-utils é Fase 2.
• Risco: baixo — assinaturas públicas mantidas, suíte de testes existente passa intacta, novas funções são puramente aditivas.
• Bundle size: ~11.5KB gzip agregado (vanilla-masker ~3KB + cpf-cnpj-validator ~7KB + código novo ~1.5KB). Discutido e aceito no spec (RNF-03 do PRD revogado).

Cenários de teste

• maskValue('11222333000181', 'cnpj') → '11.222.333/0001-81' (numérico — retrocompat)
• maskValue('12ABC34501DE35', 'cnpj') → '12.ABC.345/01DE-35' (alfanumérico)
• maskValue('12abc34501de35', 'cnpj') → '12.ABC.345/01DE-35' (minúsculo normaliza)
• maskCpfOrCnpj('93231097037') → '932.310.970-37' (CPF, ≤11 chars)
• maskCpfOrCnpj('12ABC34501DE35') → '12.ABC.345/01DE-35' (CNPJ alfa, >11 chars)
• maskInput(input, 'cpf') aplica máscara em tempo real ao digitar e pode ser desfeito via teardown
• setupMultipleMask(input) transiciona de CPF → CNPJ ao digitar o 12º caractere
• isCnpj(cnpj.generate()) → true (CNPJ alfa válido gerado pela própria lib)
• isCnpj('12ABC34501DE99') → false (DV alfa errado)
• isCnpj('00000000000000') → false (blacklist numérica preservada via lib)
• formatCnpj('11222333000181') → '11.222.333/0001-81' (regressão numérica)
• formatCnpj('12abc34501de35') → '12.ABC.345/01DE-35' (alfa + uppercase)
• maskComplete('12.ABC.345/01DE-35', 'cnpj') → true
• maskHintBankAccount('1') → '00000000-0' (BB)

Validações automáticas: yarn build, yarn lint, yarn test --testPathPattern=\"masks|formatCnpj|isCnpj|normalizeCpfOrCnpj\" (10 suítes, 63 testes verdes localmente).

Breaking changes

Nenhum em assinaturas públicas. Mudanças de comportamento documentar no CHANGELOG da 1.3.0:

• formatCnpj agora preserva letras A-Z e normaliza para uppercase. MFEs que assumiam retorno numérico devem ser auditados na Fase 2.
• isCnpj(value, strict) ignora strict (soft deprecation). A lib cpf-cnpj-validator aceita ambos os formatos por padrão.
• verifierDigit antes exportado como named export em src/validations/isCnpj.ts foi removido (decisão registrada no spec).

Dependências entre PRs

• Pós-merge: PR no Pagnet/mfe-core bumpando @useblu/utils para 1.3.0 é hand-off para a squad Core (T9 do plano de execução do spec).

Rollback

• Rollback seguro? Sim
• Procedimento: npm deprecate @useblu/utils@1.3.0 + revert do bump no mfe-core quando aplicado. Como nenhum MFE consome a nova API ainda, o impacto de rollback é zero no curto prazo.

Links

• PRD/Spec: #32 (PRD no corpo da issue, Spec Técnico no comentário #issuecomment-4392531620)
• Jira: OR-145 — Unificar máscara de inputs no blu-utils
• Jira (parent): OR-98 — Suporte a CNPJ Alfanumérico
• Referência regulatória: Nota Técnica RFB NT 49/2024

[acassiovilasboas]

@claude

[danimuller20]

Eu não sei se foi feito, mas seria interessante atualizar a base de conhecimento