🚀 Essencials

Uma biblioteca essencial de componentes React e utilitários JavaScript/TypeScript para acelerar o desenvolvimento web

📦 Instalação

npm install essencials

ou

yarn add essencials

📖 Sobre

Essencials é uma biblioteca que reúne componentes React reutilizáveis e utilitários JavaScript essenciais para o dia a dia do desenvolvedor. Com foco em produtividade e qualidade de código, a biblioteca oferece soluções prontas para problemas comuns no desenvolvimento web.

✨ Funcionalidades

🎨 Componentes React

• Button - Botão customizável com suporte a estilos
• DefaultPage - Página padrão com header e estrutura base

🛠️ Utilitários

• ArrayUtils - Manipulação e operações com arrays
• ValueUtils - Formatação de valores e cálculos financeiros (PT-BR)
• SearchUtils - Busca genérica em arrays de objetos
• StringUtils - Manipulação de strings
• ValidateUtils - Validação de CPF e outros dados
• CookieUtils - Gerenciamento de cookies
• CommonUtils - Utilitários gerais (telefone, objetos, exportação CSV)

📚 Documentação Completa

🎨 Componentes

Button

Componente de botão customizável que estende as propriedades nativas do HTML button.

import { Button } from 'essencials';

function App() {
  return (
    <Button 
      backgroundColor="#007bff" 
      color="#ffffff"
      onClick={() => console.log('Clicado!')}
    >
      Clique Aqui
    </Button>
  );
}

Props:

• backgroundColor?: string - Cor de fundo do botão
• color?: string - Cor do texto
• Todas as props nativas de HTMLButtonElement

DefaultPage

Componente de página padrão com header estruturado.

import { DefaultPage } from 'essencials';

function App() {
  return (
    <DefaultPage 
      companyName="Minha Empresa"
      companyImage="/logo.png"
      customStyles={{ padding: '20px' }}
    >
      <main>Conteúdo da página</main>
    </DefaultPage>
  );
}

Props:

• companyName?: string - Nome da empresa exibido no header
• companyImage?: string - URL da imagem/logo
• customStyles?: React.CSSProperties - Estilos customizados
• Todas as props nativas de HTMLDivElement

🛠️ Utilitários

ArrayUtils

Utilitários para manipulação de arrays.

import { ArrayUtils } from 'essencials';

// Busca linear
const encontrado = ArrayUtils.linearSearch([1, 2, 3, 4], 3); // true

// Verificar igualdade entre arrays
const saoIguais = ArrayUtils.checkEqualsFromArrays(['a', 'b'], ['b', 'c']); // true

// Gerar opções de parcelamento
const opcoes = ArrayUtils.generatePaymentMethodOptions(12);
// ['1x', '2x', '3x', ..., '12x']

Métodos:

• linearSearch(haystack: number[], needle: number): boolean
• checkEqualsFromArrays(arrayA: any[], arrayB: any[]): boolean
• generatePaymentMethodOptions(size: number): string[]

ValueUtils

Utilitários para formatação de valores e cálculos financeiros (localização PT-BR).

import { ValueUtils } from 'essencials';

// Formatar valor em Real Brasileiro
const valorFormatado = ValueUtils.formatValuePtBr(1299.99);
// "R$ 1.299,99"

// Calcular subtotal com desconto
const subtotal = ValueUtils.calculateSubtotalWithDiscount(100, 3, 10);
// 100 * 3 - 10% = 270.00

Métodos:

• formatValuePtBr(value: number): string
• calculateSubtotalWithDiscount(value: number, quantity: number, discount: number | null | undefined): number

SearchUtils

Busca genérica e tipada em arrays de objetos.

import { SearchUtils } from 'essencials';

interface Usuario {
  id: number;
  nome: string;
  email: string;
}

const usuarios: Usuario[] = [
  { id: 1, nome: 'João Silva', email: '[email protected]' },
  { id: 2, nome: 'Maria Santos', email: '[email protected]' }
];

// Buscar por múltiplos campos
const resultado = SearchUtils.findItem(usuarios, ['nome', 'email'], 'maria');
// { id: 2, nome: 'Maria Santos', email: '[email protected]' }

Métodos:

• findItem<T>(data: T[], fields: (keyof T)[], searchValue: string | number): NonNullable<T> | undefined

StringUtils

Utilitários para manipulação de strings.

import { StringUtils } from 'essencials';

// Capitalizar palavras
const texto = StringUtils.capitalizeWords('olá mundo javascript');
// "Olá Mundo Javascript"

Métodos:

• capitalizeWords(sentence: string): string

ValidateUtils

Validadores para dados brasileiros.

import { ValidateUtils } from 'essencials';

// Validar CPF
const cpfValido = ValidateUtils.isValidCPF('123.456.789-09'); // true ou false
const cpfSemMascara = ValidateUtils.isValidCPF('12345678909'); // funciona com ou sem máscara

Métodos:

• isValidCPF(cpf: string): boolean - Valida CPF com ou sem máscara

CookieUtils

Gerenciamento completo de cookies no browser.

import { CookieUtils } from 'essencials';

// Definir cookie (expira em 7 dias)
CookieUtils.setCookie({ token: 'abc123', userId: '456' }, 7);

// Recuperar cookie
const token = CookieUtils.getCookie('token'); // 'abc123'

// Deletar cookie
CookieUtils.deleteCookie('token');

Métodos:

• setCookie(cookieData: { [key: string]: string }, days: number): void
• getCookie(name: string): string | null
• deleteCookie(name: string): void

CommonUtils

Utilitários gerais e auxiliares.

import { CommonUtils } from 'essencials';

// Validar telefone brasileiro (11 dígitos)
const telefoneValido = CommonUtils.isValidPhone('11987654321'); // true

// Verificar se é objeto puro
const ehObjeto = CommonUtils.isObject({ nome: 'João' }); // true
const ehObjeto2 = CommonUtils.isObject([1, 2, 3]); // false
const ehObjeto3 = CommonUtils.isObject(new Date()); // false

// Exportar dados para CSV
const dados = [
  { nome: 'João', idade: 25, cidade: 'São Paulo' },
  { nome: 'Maria', idade: 30, cidade: 'Rio de Janeiro' }
];

CommonUtils.exportToCSV(dados);
// Faz download automático de 'export.csv' com os dados formatados

Métodos:

• isValidPhone(phone: string): boolean - Valida telefone brasileiro (11 dígitos)
• isObject(value: any): value is { [key: string]: any } - Type guard para objetos puros
• exportToCSV(bodyList: any[]): void - Exporta array de objetos para arquivo CSV com encoding UTF-8

🎯 Casos de Uso

Exemplo Completo: Formulário com Validação

import React, { useState } from 'react';
import { 
  Button, 
  ValidateUtils, 
  CommonUtils, 
  StringUtils,
  ValueUtils 
} from 'essencials';

function FormularioContato() {
  const [cpf, setCpf] = useState('');
  const [telefone, setTelefone] = useState('');
  const [nome, setNome] = useState('');

  const handleSubmit = () => {
    if (!ValidateUtils.isValidCPF(cpf)) {
      alert('CPF inválido!');
      return;
    }

    if (!CommonUtils.isValidPhone(telefone)) {
      alert('Telefone inválido!');
      return;
    }

    const nomeFormatado = StringUtils.capitalizeWords(nome);
    console.log('Enviando:', { cpf, telefone, nome: nomeFormatado });
  };

  return (
    <form>
      <input 
        placeholder="Nome completo"
        value={nome}
        onChange={(e) => setNome(e.target.value)}
      />
      <input 
        placeholder="CPF"
        value={cpf}
        onChange={(e) => setCpf(e.target.value)}
      />
      <input 
        placeholder="Telefone"
        value={telefone}
        onChange={(e) => setTelefone(e.target.value)}
      />
      <Button 
        backgroundColor="#28a745" 
        color="white"
        onClick={handleSubmit}
      >
        Enviar
      </Button>
    </form>
  );
}

Exemplo: Exportação de Relatório

import { CommonUtils, ValueUtils } from 'essencials';

const vendas = [
  { produto: 'Notebook', valor: 2500, quantidade: 2 },
  { produto: 'Mouse', valor: 50, quantidade: 10 },
  { produto: 'Teclado', valor: 150, quantidade: 5 }
];

// Formatar valores antes de exportar
const vendasFormatadas = vendas.map(venda => ({
  produto: venda.produto,
  valorUnitario: ValueUtils.formatValuePtBr(venda.valor),
  quantidade: venda.quantidade,
  total: ValueUtils.formatValuePtBr(venda.valor * venda.quantidade)
}));

// Exportar para CSV
CommonUtils.exportToCSV(vendasFormatadas);

🔧 Tecnologias

• TypeScript - Tipagem estática
• React 18.x - Componentes modernos
• ESM & CommonJS - Suporte a ambos os formatos de módulo

📦 Build & Distribuição

O pacote é distribuído em dois formatos:

• ESM (ES Modules): dist/esm/ - Para bundlers modernos (Vite, Webpack 5+)
• CommonJS: dist/cjs/ - Para Node.js e compatibilidade legada

{
  "main": "dist/cjs/index.js",
  "module": "dist/esm/index.js"
}

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para:

1. Fazer fork do projeto
2. Criar uma branch para sua feature (git checkout -b feature/MinhaFeature)
3. Commit suas mudanças (git commit -m 'Adiciona nova feature')
4. Push para a branch (git push origin feature/MinhaFeature)
5. Abrir um Pull Request

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

👤 Autor

wnn (Winnicius Moura)

• GitHub: @Winnicius-Moura
• NPM: essencials

📊 Changelog

v2.0.3 (Atual)

• ✨ Adicionadas classes utilitárias completas
• 🎨 Componentes React Button e DefaultPage
• 📦 Suporte ESM e CommonJS
• 🌍 Localização PT-BR para formatação de valores
• 📄 Exportação para CSV com encoding UTF-8

🔮 Roadmap

• [ ] Adicionar mais componentes React (Input, Modal, Card)
• [ ] Validação de CNPJ
• [ ] Máscaras para inputs (CPF, telefone, CEP)
• [ ] Utilitários de data/hora
• [ ] Hooks React customizados
• [ ] Temas e sistema de design

⭐ Mostre seu apoio

Se este projeto te ajudou, considere dar uma ⭐️ no GitHub!