vue-formatix 🚀

A modern mask and data formatting library for Vue 3, focused on Brazilian standards.

Formatação elegante para Vue 3 com foco em dados brasileiros. Funções puras, API simples e DX impecável. ✨

Destaques

• Vue 3+ 🇧🇷
• TypeScript completo 🛠️
• Tree‑shakeable ✅
• Funções puras (sem DOM) 🧩
• Composable useMask e diretiva v-mask 🔧

Instalação 📦

• npm install vue-formatix
• yarn add vue-formatix
• pnpm add vue-formatix

Requisitos ✅

• vue ^3.3.0
• Node >= 18

Uso básico 🧠

import maskData from "vue-formatix";
const mask = maskData();

mask.CPF("12345678901"); // "123.456.789-01"
mask.CNH("12345678900"); // "12345678900"
mask.Passport("AB123456"); // "AB123456"
mask.altura(1.75); // "1,75 m"
mask.cm(175); // "175 cm"
mask.mt(1.75); // "1,75 m"
mask.kg(80.5); // "80,5 kg"
mask.lb(180); // "180 lb"
mask.dataFormat01("2025-01-01"); // "01/01/2025"
mask.RUC("12345678901"); // "12345678901"
mask.phone("+55", "44999998888"); // "+55 (44) 99999-8888"
mask.brl(true, 10000); // "R$ 10.000,00"
mask.usd(true, 10000); // "$10,000.00"

Composable useMask 🧩

import { computed, ref } from "vue";
import { useMask } from "vue-formatix";

const cpf = ref("");
const mask = useMask();

const cpfFormatado = computed(() => mask.CPF(cpf.value));

Diretiva v-mask 🔧

<input v-mask.cpf v-model="cpf" />
<input v-mask.phone.br v-model="telefone" />
<input v-mask.date-ddmmyyyy v-model="data" />

Modificadores disponíveis:

• v-mask.cpf
• v-mask.phone.br
• v-mask.date-ddmmyyyy

Plugin Vue 3 🧩

import { createApp } from "vue";
import App from "./App.vue";
import { VueFormatixPlugin } from "vue-formatix/vue";

createApp(App).use(VueFormatixPlugin).mount("#app");

Exports ✨

• vue-formatix → default maskData() e exports nomeados (core)
• vue-formatix/vue → exports para integração Vue (useMask, vMask, VueFormatixPlugin)
• Subpaths:
  • vue-formatix/vue/useMask
  • vue-formatix/vue/directives/mask
  • vue-formatix/vue/plugin

Métodos 📚

| Método | Descrição | Exemplo de entrada | Exemplo de saída | | ------------------- | --------------------------- | ---------------------- | ----------------------- | | mask.CPF | Formata CPF | "12345678901" | "123.456.789-01" | | mask.CNH | Normaliza CNH (11 dígitos) | "12345678900" | "12345678900" | | mask.Passport | 2 letras + 6 dígitos | "AB123456" | "AB123456" | | mask.altura | Metros com vírgula | 1.75 | "1,75 m" | | mask.cm | Centímetros inteiros | 175 | "175 cm" | | mask.mt | Metros com vírgula | 1.75 | "1,75 m" | | mask.kg | Quilos (1 casa dec.) | 80.5 | "80,5 kg" | | mask.lb | Libras | 180 | "180 lb" | | mask.dataFormat01 | YYYY-MM-DD → DD/MM/YYYY | "2025-01-01" | "01/01/2025" | | mask.RUC | Dígitos (8–14) | "12345678901" | "12345678901" | | mask.phone | Telefone BR | "+55", "44999998888" | "+55 (44) 99999-8888" | | mask.brl | Moeda BRL (pt-BR) | true, 10000 | "R$ 10.000,00" | | mask.usd | Moeda USD (en-US) | true, 10000 | "$10,000.00" |

Tratamento de erros ⚠️

• CPF: TypeError se vazio; RangeError se tamanho ≠ 11
• CNH: TypeError se vazio; RangeError se tamanho ≠ 11
• Passport: TypeError se vazio; RangeError se formato inválido
• altura/cm/mt/kg/lb: TypeError se nulo/undefined/NaN
• dataFormat01: TypeError se vazio; RangeError se inválido
• RUC: TypeError se vazio; RangeError se tamanho fora de 8–14
• phone: TypeError se código/número vazio; RangeError se BR com tamanho inválido
• brl/usd: TypeError se nulo/undefined/NaN

Scripts 🛠️

• build: tsup
• test: vitest
• lint: eslint --ext .ts,.tsx src
• prepare: npm run build

Testes 🧪

• Rodar testes: npm test
• Exemplos em tests/:
  • cpf.spec.ts
  • data.spec.ts
  • phone-br.spec.ts

Estrutura do projeto 📁

src/
  index.ts
  core/
    cpf.ts
    cnh.ts
    passport.ts
    altura.ts
    cm.ts
    mt.ts
    kg.ts
    lb.ts
    data.ts
    ruc.ts
    phone.ts
  vue/
    useMask.ts
    directives/
      mask.ts
    plugin.ts
    index.ts
tests/
  cpf.spec.ts
  data.spec.ts
  phone-br.spec.ts
package.json
tsconfig.json
tsup.config.ts
README.md

Roadmap 🧭

• CNPJ
• CEP
• Placa veicular Mercosul
• PIS/PASEP
• RG/IE/IM por estado

Como contribuir 🤝

• Faça fork
• Crie uma branch
• Abra um PR com descrição e exemplos

Licença 📄

MIT — veja o arquivo LICENSE (quando disponível).

English Version (soon) 🇺🇸