Feature/format smart title case

docs/formatters/index.md

@@ -15,3 +15,9 @@ Funções para aplicação ou remoção de máscaras em CPFs.
 Funções para aplicação ou remoção de máscaras em números telefônicos brasileiros.
 
 - [Documentação](./phone.md)
+
+### SmartTitleCase
+
+Função para normalizar e formatar títulos, nomes próprios e frases.
+
+- [Documentação](./smartTitleCase.md)

docs/formatters/smartTitleCase.md

@@ -0,0 +1,49 @@
+# Utilitários de Formatação do SmartTitleCase
+
+Este módulo fornece funções para normalizar e formatar textos, aplicando regras de capitalização inteligente em títulos, nomes próprios e frases, respeitando preposições, conjunções e exceções definidas.
+
+## Instalação e Importação
+
+```typescript
+import { smartTitleCase } from '@sysvale/foundry';
+```
+
+## Funções
+
+### `smartTitleCase()`
+
+Formata uma string colocando a primeira letra de cada palavra em maiúsculo e o restante em minúsculo, exceto
+preposições e palavras listadas como exceção.
+
+### Sintaxe
+
+```typescript
+smartTitleCase(value: string, exceptions?: string[]): string
+```
+
+### Parâmetros
+
+- **`value`** (`string`): String que será formatada.
+
+- **`exceptions`** (`string[], opcional`): Lista de palavras que não serão formatadas, mesmo que estejam no início da string (ex.: ['da', 'de', 'UNIVASF']).
+
+### Retorno
+
+`string` - A string formatada no estilo “Title Case”, respeitando a lista de exceções, caso seja fornecida.
+
+### Exemplos
+
+<!-- prettier-ignore -->
+```typescript
+smartTitleCase('ash ketchum da silva');             // → 'Ash Ketchum da Silva'
+smartTitleCase('ASH KETCHUM DA SILVA');             // → 'Ash Ketchum da Silva'
+smartTitleCase('ash ketchum dA Silva');             // → 'Ash Ketchum da Silva'
+smartTitleCase('ESTUDANTE DA UNIVASF', ['UNIVASF']); // → 'Estudante da UNIVASF'
+smartTitleCase('');                                 // → ''
+```
+
+### Casos de Uso
+
+- Exibir nomes próprios corretamente capitalizados em formulários e relatórios.
+- Normalizar títulos, subtítulos e textos para interfaces de usuário.
+- Evitar capitalização incorreta de preposições, conjunções e siglas.

docs/index.md

@@ -67,6 +67,12 @@ git clone https://github.com/Sysvale/foundry
 npm i
 ```
 
+## Executando o Foundry
+
+```bash
+npm run docs:dev
+```
+
 A aplicação estará disponível na porta `5173`, em [http://localhost:5173/](http://localhost:5173/).
 
 ### Testando-o

package.json

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

src/formatters/smartTitleCase.ts

@@ -0,0 +1,27 @@
+const prepositions: Set<string> = new Set(['da', 'de', 'do', 'das', 'dos']);
+
+export function smartTitleCase(
+	text: string,
+	exceptions: string[] | null = null
+): string {
+	if (!text) return '';
+
+	const words = text.trim().split(/\s+/);
+	const defaultExceptions = new Set(exceptions);
+
+	return words
+		.map((originalWord: string) => {
+			const lower = originalWord.toLowerCase();
+
+			if (prepositions.has(lower)) {
+				return lower;
+			}
+
+			if (defaultExceptions.has(originalWord)) {
+				return originalWord;
+			}
+
+			return lower.charAt(0).toUpperCase() + lower.slice(1);
+		})
+		.join(' ');
+}

tests/smartTitleCase.test.ts

@@ -0,0 +1,16 @@
+import { describe, test, expect } from 'vitest';
+import { smartTitleCase } from '../src/formatters/smartTitleCase';
+
+describe('smartTitleCase', () => {
+	test('deve formatar strings', () => {
+		expect(smartTitleCase('ash ketchum da silva')).toBe('Ash Ketchum da Silva');
+		expect(smartTitleCase('Ash Ketchum da Silva')).toBe('Ash Ketchum da Silva');
+		expect(smartTitleCase('ASH KETCHUM DA SILVA')).toBe('Ash Ketchum da Silva');
+		expect(smartTitleCase('ash ketchum dA Silva')).toBe('Ash Ketchum da Silva');
+		expect(smartTitleCase('')).toBe('');
+
+		expect(smartTitleCase('ESTUDANTE DAS USP', ['USP', 'UNIVASF'])).toBe(
+			'Estudante das USP'
+		);
+	});
+});