Feature/formatters

docs/formatters/cpf.md

@@ -0,0 +1,97 @@
+# Utilitários de Formatação de CPF
+
+Este módulo fornece funções para aplicar e remover a máscara de CPF (Cadastro de Pessoas Físicas) em strings, facilitando a manipulação e exibição de documentos no padrão brasileiro.
+
+## Instalação e Importação
+
+```typescript
+import { maskCpf, removeCpfMask } from '@sysvale/foundry';
+```
+
+## Funções
+
+### `maskCpf()`
+
+Aplica a máscara de CPF no formato `XXX.XXX.XXX-XX` a uma string contendo apenas números.
+
+#### Sintaxe
+
+```typescript
+maskCpf(value: string): string
+```
+
+#### Parâmetros
+
+- **`value`** (`string`): String contendo apenas números ou um CPF já formatado.
+
+#### Retorno
+
+`string` – O CPF formatado no padrão `XXX.XXX.XXX-XX` se a entrada tiver 11 dígitos. Caso contrário, retorna apenas os dígitos informados.
+
+#### Exemplos
+
+```typescript
+maskCpf('11111111111'); // → '111.111.111-11'
+maskCpf(''); // → ''
+maskCpf('1234567890'); // → '1234567890' (menos de 11 dígitos, retorna sem máscara)
+```
+
+#### Casos de Uso
+
+- Exibir CPF formatado em formulários e relatórios.
+- Garantir consistência visual de documentos em interfaces de usuário.
+
+---
+
+### `removeCpfMask()`
+
+Remove qualquer máscara de CPF, retornando apenas os dígitos numéricos.
+
+#### Sintaxe
+
+```typescript
+removeCpfMask(value: string): string
+```
+
+#### Parâmetros
+
+- **`value`** (`string`): String contendo um CPF formatado ou não.
+
+#### Retorno
+
+`string` – String contendo apenas os números do CPF.
+
+#### Exemplos
+
+```typescript
+removeCpfMask('111.111.111-11'); // → '11111111111'
+removeCpfMask(''); // → ''
+removeCpfMask('1234567890'); // → '1234567890' (não altera se não houver máscara)
+```
+
+#### Casos de Uso
+
+- Armazenar CPFs em banco de dados sem formatação.
+- Validar ou comparar CPFs independentemente do formato de entrada.
+
+## Casos de Uso Comuns
+
+### Formatação para exibição
+
+```typescript
+const cpf = '12345678901';
+const formatted = maskCpf(cpf); // '123.456.789-01'
+```
+
+### Remoção de máscara para validação
+
+```typescript
+const masked = '123.456.789-01';
+const digits = removeCpfMask(masked); // '12345678901'
+```
+
+## Limitações
+
+- As funções não validam se o CPF é válido, apenas formatam ou removem a máscara.
+- Se a string de entrada não tiver 11 dígitos, `maskCpf` retorna apenas os dígitos sem aplicar a máscara.
+- Caracteres não numéricos são removidos por `removeCpfMask`.

docs/formatters/index.md

@@ -0,0 +1,17 @@
+# Utilitários de Formatação
+
+Este módulo fornece funções para formatar diversos tipos de dados.
+
+## Formatadores
+
+### CPF
+
+Funções para aplicação ou remoção de máscaras em CPFs.
+
+- [Documentação](./cpf.md)
+
+### Telefone
+
+Funções para aplicação ou remoção de máscaras em números telefônicos brasileiros.
+
+- [Documentação](./phone.md)

docs/formatters/phone.md

@@ -0,0 +1,110 @@
+# Utilitários de Formatação de Telefone
+
+Este módulo fornece funções para aplicar e remover a máscara de números de telefone brasileiros, facilitando a manipulação e exibição de telefones fixos e celulares no padrão nacional.
+
+## Instalação e Importação
+
+```typescript
+import { maskPhone, removePhoneMask } from '@sysvale/foundry';
+```
+
+## Funções
+
+### `maskPhone()`
+
+Aplica a máscara de telefone brasileiro no formato `(XX) XXXXX-XXXX` para celulares (11 dígitos) ou `(XX) XXXX-XXXX` para fixos (10 dígitos).
+
+#### Sintaxe
+
+```typescript
+maskPhone(value: string): string
+```
+
+#### Parâmetros
+
+- **`value`** (`string`): String contendo apenas números, telefone já formatado ou com caracteres especiais.
+
+#### Retorno
+
+`string` – O telefone formatado no padrão nacional, conforme a quantidade de dígitos. Se a entrada não tiver 10 ou 11 dígitos, retorna apenas os dígitos informados.
+
+#### Exemplos
+
+<!-- prettier-ignore -->
+```typescript
+maskPhone('11987654321');      // → '(11) 98765-4321'
+maskPhone('1187654321');       // → '(11) 8765-4321'
+maskPhone('');                 // → ''
+maskPhone('123456789');        // → '123456789' (menos de 10 dígitos, retorna sem máscara)
+maskPhone('(11) 98765-4321');  // → '(11) 98765-4321' (já formatado)
+maskPhone('11.98765.4321');    // → '(11) 98765-4321'
+maskPhone('11abc98765def4321');// → '(11) 98765-4321'
+maskPhone('1');                // → '1'
+```
+
+#### Casos de Uso
+
+- Exibir telefones formatados em formulários e relatórios.
+- Garantir consistência visual de números de telefone em interfaces de usuário.
+
+---
+
+### `removePhoneMask()`
+
+Remove qualquer máscara de telefone, retornando apenas os dígitos numéricos.
+
+#### Sintaxe
+
+```typescript
+removePhoneMask(value: string): string
+```
+
+#### Parâmetros
+
+- **`value`** (`string`): String contendo um telefone formatado ou não.
+
+#### Retorno
+
+`string` – String contendo apenas os números do telefone.
+
+#### Exemplos
+
+<!-- prettier-ignore -->
+```typescript
+removePhoneMask('(11) 98765-4321');      // → '11987654321'
+removePhoneMask('(11) 8765-4321');       // → '1187654321'
+removePhoneMask('');                     // → ''
+removePhoneMask('11987654321');          // → '11987654321' (sem máscara, retorna igual)
+removePhoneMask('11 98765 4321');        // → '11987654321'
+removePhoneMask('11.98765.4321');        // → '11.98765.4321' (pontos não são removidos)
+removePhoneMask('11#98765#4321');        // → '11#98765#4321' (outros caracteres não são removidos)
+removePhoneMask('(11) 98765-4321 ext.123'); // → '11987654321ext.123'
+```
+
+#### Casos de Uso
+
+- Armazenar telefones em banco de dados sem formatação.
+- Validar ou comparar telefones independentemente do formato de entrada.
+- Remover apenas os caracteres de máscara padrão: parênteses, hífens e espaços.
+
+## Casos de Uso Comuns
+
+### Formatação para exibição
+
+```typescript
+const phone = '11987654321';
+const formatted = maskPhone(phone); // '(11) 98765-4321'
+```
+
+### Remoção de máscara para validação
+
+```typescript
+const masked = '(11) 98765-4321';
+const digits = removePhoneMask(masked); // '11987654321'
+```
+
+## Limitações
+
+- As funções não validam se o número de telefone é válido, apenas formatam ou removem a máscara.
+- Se a string de entrada não tiver 10 ou 11 dígitos, `maskPhone` retorna apenas os dígitos sem aplicar a máscara.
+- `removePhoneMask` remove apenas parênteses, hífens e espaços; outros caracteres especiais permanecem.

docs/index.md

@@ -8,8 +8,11 @@ hero:
 
 features:
   - title: Utils
-    details: Métodos utilitários em TypesCript para facilitar tarefas comuns no front-end.
+    details: Métodos utilitários em TypeScript para facilitar tarefas comuns no front-end.
     link: /utils/pluralize
+  - title: Formatadores
+    details: Métodos em TypeScript para formatar diversos tipos de dados.
+    link: /formatters/index
   - title: Composables
     details: Composables Vue 3 reutilizáveis para lógica comum no front-end.
     link: /composables/

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sysvale/foundry",
-	"version": "1.0.0",
+	"version": "1.1.0",
 	"description": "A forge for composables, helpers, and front-end utilities.",
 	"type": "module",
 	"main": "./dist/foundry.cjs.js",

src/formatters/cpf.ts

@@ -0,0 +1,27 @@
+const maskCpf = (value: string | number) => {
+	let cpf = typeof value === 'number' ? value.toString() : value;
+
+	if (!cpf) {
+		return '';
+	}
+
+	cpf = cpf.replace(/\D/g, '');
+
+	if (cpf.length === 11) {
+		return `${cpf.substring(0, 3)}.${cpf.substring(3, 6)}.${cpf.substring(6, 9)}-${cpf.substring(9, 11)}`;
+	}
+
+	return cpf;
+};
+
+const removeCpfMask = (value: string | number) => {
+	let cpf = typeof value === 'number' ? value.toString() : value;
+
+	if (!cpf) {
+		return '';
+	}
+
+	return cpf.replace(/\D/g, '');
+};
+
+export { maskCpf, removeCpfMask };

src/formatters/phone.ts

@@ -0,0 +1,30 @@
+const maskPhone = (value: string | null | number | undefined) => {
+	let phone = typeof value === 'number' ? value.toString() : value;
+
+	if (!phone || phone.length === 0) {
+		return '';
+	}
+
+	phone = phone.replace(/[^0-9]+/g, '');
+
+	if (phone.length === 11) {
+		return `(${phone.substring(0, 2)}) ${phone.substring(2, 7)}-${phone.substring(7, 11)}`;
+	}
+
+	if (phone.length === 10) {
+		return `(${phone.substring(0, 2)}) ${phone.substring(2, 6)}-${phone.substring(6, 10)}`;
+	}
+	return phone;
+};
+
+const removePhoneMask = (value: string | null | number | undefined) => {
+	let phone = typeof value === 'number' ? value.toString() : value;
+
+	if (!phone || phone.length === 0) {
+		return '';
+	}
+
+	return phone.replace(/\(|\)|-|\s/g, '');
+};
+
+export { maskPhone, removePhoneMask };

src/index.ts

@@ -1 +1,3 @@
 export * from './utils/pluralize';
+export { maskCpf, removeCpfMask } from './formatters/cpf';
+export { maskPhone, removePhoneMask } from './formatters/phone';

tests/cpf.test.ts

@@ -0,0 +1,31 @@
+import { describe, test, expect } from 'vitest';
+import { maskCpf, removeCpfMask } from '../src/formatters/cpf';
+
+describe('maskCpf', () => {
+	test('deve formatar cpf', () => {
+		expect(maskCpf('11111111111')).toBe('111.111.111-11');
+		expect(maskCpf(11111111111)).toBe('111.111.111-11');
+	});
+
+	test('deve retornar string vazia quando cpf é vazio', () => {
+		expect(maskCpf('')).toBe('');
+	});
+
+	test('deve retornar valor como está quando cpf é inválido', () => {
+		expect(maskCpf('1234567890')).toBe('1234567890');
+	});
+});
+
+describe('removeCpfMask', () => {
+	test('deve remover máscara de cpf', () => {
+		expect(removeCpfMask('111.111.111-11')).toBe('11111111111');
+	});
+
+	test('deve retornar string vazia quando cpf é vazio', () => {
+		expect(removeCpfMask('')).toBe('');
+	});
+
+	test('deve retornar valor como está quando cpf é inválido', () => {
+		expect(removeCpfMask('1234567890')).toBe('1234567890');
+	});
+});