diff --git a/docs/formatters/index.md b/docs/formatters/index.md index 679d012..af3040f 100644 --- a/docs/formatters/index.md +++ b/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) diff --git a/docs/formatters/smartTitleCase.md b/docs/formatters/smartTitleCase.md new file mode 100644 index 0000000..a4bbeb5 --- /dev/null +++ b/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 + + +```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. diff --git a/docs/index.md b/docs/index.md index 993f842..8872ac2 100644 --- a/docs/index.md +++ b/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 diff --git a/package.json b/package.json index b2c4193..ef7c7c9 100644 --- a/package.json +++ b/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", diff --git a/src/formatters/smartTitleCase.ts b/src/formatters/smartTitleCase.ts new file mode 100644 index 0000000..cfb330d --- /dev/null +++ b/src/formatters/smartTitleCase.ts @@ -0,0 +1,27 @@ +const prepositions: Set = 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(' '); +} diff --git a/tests/smartTitleCase.test.ts b/tests/smartTitleCase.test.ts new file mode 100644 index 0000000..a8aed32 --- /dev/null +++ b/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' + ); + }); +});