Front Commons - Biblioteca Vue 3

Biblioteca de componentes, funções e utils compartilhados para projetos Vue 3 do Clube Certo.

📦 Instalação

Via NPM (Recomendado)

npm install @clube-certo/front-commons

Via Git

npm install git+https://github.com/clubecerto/front-commons.git

🚀 Uso

Importando Componentes

<template>
  <div>
    <AutoComplete
      v-model="selectedUser"
      :search-fn="searchUsers"
      placeholder="Buscar usuário..."
    />

    <Input
      v-model="inputValue"
      placeholder="Digite algo..."
      type="text"
    />
  </div>
</template>

<script setup>
import { ref } from "vue";
// Importação direta dos componentes Vue
import AutoComplete from "@clube-certo/front-commons/src/components/generic/AutoComplete.vue";
import Input from "@clube-certo/front-commons/src/components/generic/Input.vue";

const selectedUser = ref(null);
const inputValue = ref("");

const searchUsers = async (term) => {
  // Implementar busca de usuários
  return [];
};
</script>

Importando Utilitários e Composables

// Importação de utilitários e composables (disponíveis no bundle principal)
import { formatCurrency, formatCPF, isValidEmail, httpClient, useApi, useLocalStorage } from "@clube-certo/front-commons";

Usando Utilitários

import { formatCurrency, formatCPF, isValidEmail, httpClient } from "@clube-certo/front-commons";

// Formatação
const price = formatCurrency(1234.56); // R$ 1.234,56
const cpf = formatCPF("12345678901"); // 123.456.789-01

// Validação
const isValid = isValidEmail("[email protected]"); // true

// API
const response = await httpClient.get("/api/users");

Usando Composables

<script setup>
import { ref } from "vue";
import { useApi, useLocalStorage, useValidation, useClipboard } from "@clube-certo/front-commons";

// API
const { data: users, loading, error } = useApi("/api/users");

// Storage
const [theme, setTheme] = useLocalStorage("theme", "light");

// Validação
const { data, errors, validate } = useValidation({
  email: { required: true, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ },
  password: { required: true, minLength: 8 },
});

// Clipboard
const { copy, copied } = useClipboard();
</script>

📚 Documentação

Componentes Disponíveis

Componentes Genéricos

Formulários e Inputs

• AutoComplete - Campo de autocomplete com busca assíncrona e seleção de itens
• DatePicker - Seletor de data avançado com suporte a range, modo mês e formatos customizáveis
• Input - Campo de entrada versátil com máscaras, validação e tipos especiais (moeda, telefone, cor, CEP)
• InputCalendar - Calendário para seleção de data/hora com suporte a datetime
• Select - Dropdown altamente customizável com busca, múltipla seleção, agrupamento e modo simples/grupo
• Toggle - Switch segmentado com rótulos e ícones personalizáveis
• ValidatorErrors - Componente para exibição estruturada de erros de validação
• RichText - Editor de texto rico com toolbar customizável

Tabelas e Listas

• GenericTable - Tabela completa com paginação, ordenação, filtros, seleção múltipla e edição inline
• HeaderList - Cabeçalho de lista com controles de busca, filtros e botões de ação
• Pagination - Componente de paginação com informações detalhadas

Modais e Diálogos

• ConfirmDialog - Modal de confirmação com botões e estilos customizáveis
• GenericDialog - Modal genérico altamente configurável e reutilizável
• ModalFileReader - Modal avançado para importação e leitura de arquivos (Excel, CSV, OFX) com preview e edição
• SideForms - Formulários laterais deslizantes com posicionamento configurável

Visualização e Feedback

• Error - Página de erro com ilustração SVG animada
• Loader - Indicador de carregamento com overlay
• PhoneMockup - Simulação de notificação push em dispositivo móvel
• PhoneMockupFullscreen - Simulação completa de tela de aplicativo móvel com múltiplos templates
• Kanban - Board Kanban com drag & drop, filtros de coluna e estados customizáveis

Utilitários

• CopyText - Botão inteligente para copiar texto para clipboard com feedback
• ExcelExportModal - Modal completo para exportação de dados para Excel com seleção de colunas e renomeação

Upload e Mídia

• Dropzone - Área de upload com drag & drop, preview de arquivos e validação
• UploadIcon - Ícone dinâmico baseado no tipo de arquivo

Mapas

• Map - Componente de mapa interativo com Google Maps, círculos, polígonos e controles de zoom/raio

Exemplos de Uso dos Componentes Genéricos

AutoComplete

<template>
  <AutoComplete
    v-model="selectedUser"
    :search-fn="searchUsers"
    placeholder="Buscar usuário..."
    label="name"
    value="id"
  />
</template>

<script setup>
import { ref } from "vue";
import AutoComplete from "@clube-certo/front-commons/src/components/generic/AutoComplete.vue";

const selectedUser = ref(null);

const searchUsers = async (term) => {
  const response = await fetch(`/api/users?search=${term}`);
  return response.json();
};
</script>

GenericTable

<template>
  <GenericTable
    :data="users"
    :columns="columns"
    :enable-pagination="true"
    :enable-selection="true"
    :editable="true"
    :editable-columns-config="editableConfig"
    @update:selectedItems="handleSelection"
  />
</template>

<script setup>
import { ref } from "vue";
import GenericTable from "@clube-certo/front-commons/src/components/generic/GenericTable.vue";

const users = ref([]);
const columns = [
  { accessorKey: "name", header: "Nome" },
  { accessorKey: "email", header: "Email" },
  { accessorKey: "status", header: "Status" },
];

const editableConfig = [
  { column: "name", type: "string" },
  {
    column: "status",
    type: "select",
    selectOptions: [
      { label: "Ativo", value: "active" },
      { label: "Inativo", value: "inactive" },
    ],
  },
];
</script>

Kanban

<template>
  <Kanban
    entity-name="tarefa"
    :items="tasks"
    id-item="id"
    :status-list="statusList"
    status-mapping="status"
    @status-change="updateTaskStatus"
  >
    <template #default="{ item }">
      <div class="task-card">
        <h3>{{ item.title }}</h3>
        <p>{{ item.description }}</p>
      </div>
    </template>
  </Kanban>
</template>

<script setup>
import { ref } from "vue";
import Kanban from "@clube-certo/front-commons/src/components/generic/Kanban.vue";

const tasks = ref([]);
const statusList = [
  { value: 1, label: "A Fazer", cor: "#ff6b6b" },
  { value: 2, label: "Em Progresso", cor: "#4ecdc4" },
  { value: 3, label: "Concluído", cor: "#45b7d1" },
];

const updateTaskStatus = (newStatus, taskId) => {
  // Atualizar status da tarefa
};
</script>

ModalFileReader

<template>
  <ModalFileReader
    title="Importar Usuários"
    type-file=".xlsx,.csv"
    entity-search="users"
    :search="true"
    :mapping="{ nome: 'name', email: 'email' }"
    @process-selected="processUsers"
    @refetch-data="refreshData"
  />
</template>

<script setup>
import ModalFileReader from "@clube-certo/front-commons/src/components/generic/ModalFileReader.vue";

const processUsers = async (users) => {
  try {
    await api.post("/users/import", { users });
    return { success: true };
  } catch (error) {
    return { error };
  }
};
</script>

DatePicker

<template>
  <div>
    <!-- Data simples -->
    <DatePicker v-model="selectedDate" />

    <!-- Seleção de mês -->
    <DatePicker
      v-model="selectedMonth"
      :month="true"
    />

    <!-- Range de datas -->
    <DatePicker
      v-model="dateRange"
      :range="true"
      :start="startDate"
      :end="endDate"
      @update:start="startDate = $event"
      @update:end="endDate = $event"
    />
  </div>
</template>

<script setup>
import { ref } from "vue";
import DatePicker from "@clube-certo/front-commons/src/components/generic/DatePicker.vue";

const selectedDate = ref(null);
const selectedMonth = ref(null);
const dateRange = ref(null);
const startDate = ref(null);
const endDate = ref(null);
</script>

📋 Documentação Detalhada dos Componentes

AutoComplete

Descrição: Campo de autocomplete com busca assíncrona e seleção de itens.

Props:

• modelValue (String/Number) - Valor selecionado
• placeHolder (String, default: 'Select framework...') - Texto placeholder
• notFoundMessage (String, default: 'No framework found.') - Mensagem quando não encontra resultados
• searchFn (Function) - Função de busca assíncrona
• label (String, default: 'label') - Propriedade para exibição do texto
• value (String, default: 'value') - Propriedade para o valor
• disabled (Boolean, default: false) - Desabilita o componente

Eventos:

• update:modelValue - Emitido quando o valor é alterado

Exemplo:

<AutoComplete v-model="selectedUser" :search-fn="searchUsers" placeholder="Buscar usuário..." label="name" value="id" :disabled="false" />

ConfirmDialog

Descrição: Modal de confirmação com botões e estilos customizáveis.

Props:

• titulo (String, required) - Título do modal
• textoConfirmacao (String, required) - Texto de confirmação
• labelBotaoCancelar (String, default: 'Cancelar') - Texto do botão cancelar
• labelBotaoConfirmar (String, default: 'Confirmar') - Texto do botão confirmar
• classBotaoCancelar (String, default: 'bg-red-100 text-red-600') - Classes CSS do botão cancelar
• classBotaoConfirmar (String, default: 'bg-green-600 text-white') - Classes CSS do botão confirmar

Eventos:

• click:button-cancelar - Emitido ao clicar em cancelar
• click:button-confirmar - Emitido ao clicar em confirmar

Slots:

• button-trigger - Slot para o botão que abre o modal

CopyText

Descrição: Botão inteligente para copiar texto para clipboard com feedback.

Props:

• text (String, required) - Texto a ser copiado
• label (String, default: '') - Rótulo do botão
• showIcon (Boolean, default: true) - Exibe ícone de cópia
• entityName (String, default: 'Texto') - Nome da entidade para feedback
• showText (Boolean, default: true) - Exibe o texto no botão

Exemplo:

<CopyText text="Texto para copiar" label="Copiar:" entity-name="Código" :show-icon="true" :show-text="true" />

DatePicker

Descrição: Seletor de data avançado com suporte a range, modo mês e formatos customizáveis.

Props:

• modelValue (DateValue/String/DateRange) - Valor da data
• placeholder (String, default: 'Selecione uma data') - Placeholder
• formatOptions (Object, default: { dateStyle: 'short' }) - Opções de formatação
• locale (String, default: 'pt-BR') - Localização
• month (Boolean, default: false) - Modo seleção de mês
• range (Boolean, default: false) - Modo range de datas
• start (DateValue) - Data inicial (modo range)
• end (DateValue) - Data final (modo range)

Eventos:

• update:modelValue - Emitido quando o valor é alterado
• update:start - Emitido quando a data inicial é alterada (modo range)
• update:end - Emitido quando a data final é alterada (modo range)

GenericTable

Descrição: Tabela completa com paginação, ordenação, filtros, seleção múltipla e edição inline.

Props:

• data (Array, required) - Dados da tabela
• columns (Array) - Configuração das colunas
• autoGenerateColumns (Boolean, default: true) - Gerar colunas automaticamente
• enablePagination (Boolean, default: true) - Habilitar paginação
• initialPageSize (Number, default: 50) - Tamanho inicial da página
• enableGlobalFilter (Boolean, default: true) - Habilitar busca global
• enableSorting (Boolean, default: true) - Habilitar ordenação
• enableSelection (Boolean, default: false) - Habilitar seleção múltipla
• selectionKey (String, default: 'id') - Chave para seleção
• editable (Boolean, default: false) - Habilitar edição
• editableColumnsConfig (Array) - Configuração de colunas editáveis

Eventos:

• update:selectedItems - Emitido quando itens são selecionados
• update:data - Emitido quando dados são editados

Input

Descrição: Campo de entrada versátil com máscaras, validação e tipos especiais.

Props:

• modelValue (String) - Valor do input
• type (String, default: 'text') - Tipo do input
• placeholder (String) - Placeholder
• size (String, default: 'default') - Tamanho do input
• disabled (Boolean, default: false) - Desabilitar input
• readonly (Boolean, default: false) - Somente leitura
• money (Boolean, default: false) - Modo moeda
• phone (Boolean, default: false) - Modo telefone
• color (Boolean, default: false) - Modo cor
• cep (Boolean, default: false) - Modo CEP
• dataMaska (String) - Máscara personalizada
• icon (String) - Ícone do input
• iconDir (String) - Direção do ícone ('left' ou 'right')

Eventos:

• update:modelValue - Emitido quando o valor é alterado
• blur - Emitido quando o input perde o foco

Kanban

Descrição: Board Kanban com drag & drop, filtros de coluna e estados customizáveis.

Props:

• entityName (String, required) - Nome da entidade
• items (Array, required) - Lista de itens
• idItem (String, required) - Campo ID dos itens
• statusList (Array, required) - Lista de status/colunas
• statusMapping (String, required) - Mapeamento do campo status
• onStatusChange (Function) - Função para alterar status
• onStatusMutation (Function) - Função alternativa para alterar status
• cardComponent (Component) - Componente do card
• loading (Boolean, default: false) - Estado de carregamento

Eventos:

• Não emite eventos diretamente, usa as funções onStatusChange ou onStatusMutation

Slots:

• default - Slot para o conteúdo do card (recebe { item })

Select

Descrição: Dropdown altamente customizável com busca, múltipla seleção e agrupamento.

Props:

• modelValue (String/Number/Array) - Valor selecionado
• multiple (Boolean, default: false) - Seleção múltipla
• options (Array, required) - Opções do select
• placeholder (String, default: 'Selecione uma opção') - Placeholder
• mode (String, default: 'simple') - Modo ('simple' ou 'group')
• clearable (Boolean, default: true) - Permitir limpar seleção
• search (Boolean, default: false) - Habilitar busca
• hideSelected (Boolean, default: false) - Ocultar itens selecionados
• label (String, default: 'label') - Propriedade para label
• value (String, default: 'value') - Propriedade para valor
• groupName (String, default: 'group') - Propriedade para agrupamento

Eventos:

• update:modelValue - Emitido quando o valor é alterado

ModalFileReader

Descrição: Modal avançado para importação e leitura de arquivos com preview e edição.

Props:

• title (String, default: 'Importação de Arquivo') - Título do modal
• description (String) - Descrição do modal
• typeFile (String, default: '.xls,.xlsx,.ofx,.csv,.numbers') - Tipos de arquivo aceitos
• entitySearch (String, default: 'noentity') - Entidade para busca
• search (Boolean, default: false) - Habilitar busca/comparação
• mapping (Object) - Mapeamento de colunas
• ofxFilter (String) - Filtro para arquivos OFX ('all', 'expenses', 'revenues')
• editable (Boolean, default: false) - Habilitar edição
• editableColumnsConfig (Array) - Configuração de colunas editáveis
• chunkSize (Number, default: 100) - Tamanho do chunk para importação
• chunkInterval (Number, default: 1000) - Intervalo entre chunks
• planilhaModeloNome (String) - Nome da planilha modelo
• dadosPlanilhaModelo (Array) - Dados da planilha modelo

Eventos:

• process-selected - Emitido para processar itens selecionados
• refetch-data - Emitido para recarregar dados

Toggle

Descrição: Switch segmentado com rótulos e ícones personalizáveis.

Props:

• modelValue (Boolean) - Valor do toggle
• leftLabel (String, default: 'One Way') - Rótulo da esquerda
• rightLabel (String, default: 'Return') - Rótulo da direita
• leftIcon (String) - Ícone da esquerda
• rightIcon (String) - Ícone da direita
• disabled (Boolean, default: false) - Desabilitar toggle
• variant (String, default: 'default') - Variante de cor

Eventos:

• update:modelValue - Emitido quando o valor é alterado

Dropzone

Descrição: Área de upload com drag & drop, preview de arquivos e validação.

Props:

• modelValue (Array, default: []) - Arquivos selecionados
• multiple (Boolean, default: false) - Múltiplos arquivos
• previews (Array, default: []) - URLs de preview
• mode (String, default: 'drop') - Modo ('drop' ou 'preview')
• disabled (Boolean, default: false) - Desabilitar componente
• accept (String) - Tipos de arquivo aceitos
• maxFileSize (Number, default: 5) - Tamanho máximo em MB
• maxFiles (Number, default: 5) - Número máximo de arquivos
• showSelectButton (Boolean, default: true) - Exibir botão de seleção

Eventos:

• drop - Emitido quando arquivos são soltos
• update:modelValue - Emitido quando arquivos são alterados
• error - Emitido em caso de erro

Slots:

• placeholder-img - Slot para imagem placeholder
• title - Slot para título
• button - Slot para botão personalizado
• description - Slot para descrição
• preview - Slot para preview personalizado

Map

Descrição: Componente de mapa interativo com Google Maps, círculos e polígonos.

Props:

• center (Object, default: { lat: 37.7749, lng: -122.4194 }) - Centro do mapa
• national (Boolean, default: false) - Modo nacional
• zoom (Number, default: 13) - Zoom inicial
• geolocations (Array, default: []) - Lista de geolocalizações

Eventos:

• update:range - Emitido quando o raio é alterado

Funcionalidades:

• Controle de raio de disparo
• Controle de zoom
• Círculos e polígonos baseados em geolocalizações
• Detecção automática de localização

Utilitários

Formatação

• formatCurrency(value, currency?, locale?) - Formatar moeda
• formatCPF(cpf) - Formatar CPF
• formatCNPJ(cnpj) - Formatar CNPJ
• formatPhone(phone) - Formatar telefone
• formatCEP(cep) - Formatar CEP
• formatDate(date, format?, locale?) - Formatar data

Cores

• hexToHSL(hex) - Converte cor hexadecimal para formato HSL
• darkenColor(hex, percent) - Escurece uma cor hexadecimal em uma porcentagem específica
• lightenColor(hex, percent) - Clareia uma cor hexadecimal em uma porcentagem específica

Exemplos de Uso das Funções de Cores

import { hexToHSL, darkenColor, lightenColor } from "@clube-certo/front-commons";

// Conversão de hexadecimal para HSL
const hslColor = hexToHSL("#00A24D"); // "123 100% 32%"
const hslFromShort = hexToHSL("#0A2"); // "123 100% 32%" (expande automaticamente)

// Escurecer uma cor
const darkerGreen = darkenColor("#00A24D", 20); // Escurece 20%
const muchDarker = darkenColor("#FF5733", 50); // Escurece 50%

// Clarear uma cor
const lighterGreen = lightenColor("#00A24D", 30); // Clareia 30%
const muchLighter = lightenColor("#FF5733", 60); // Clareia 60%

// Uso prático em temas dinâmicos
const primaryColor = "#007bff";
const hoverColor = darkenColor(primaryColor, 15);
const activeColor = darkenColor(primaryColor, 25);
const lightVariant = lightenColor(primaryColor, 40);

// Aplicação em CSS-in-JS ou estilos dinâmicos
const buttonStyles = {
  backgroundColor: primaryColor,
  ":hover": {
    backgroundColor: hoverColor,
  },
  ":active": {
    backgroundColor: activeColor,
  },
};

Validação

• isValidEmail(email) - Validar email
• isValidCPF(cpf) - Validar CPF
• isValidCNPJ(cnpj) - Validar CNPJ
• isValidPhone(phone) - Validar telefone
• isStrongPassword(password) - Validar senha forte

API

A biblioteca oferece um conjunto completo de utilitários para requisições HTTP baseados em Axios:

Funções Principais

• get<T>(controllerName, action?, extraParams?) - Requisições GET
• getQueryParams<T>(controllerName, action?, extraParams?) - GET com parâmetros customizados
• post<T>(controllerName, action?, data, extraParams?) - Requisições POST
• put<T>(controllerName, action?, data?, extraParams?) - Requisições PUT
• patch<T>(controllerName, action?, data, extraParams?) - Requisições PATCH
• del<T>(controllerName, action?, extraParams?, body?) - Requisições DELETE
• upload<T>(controllerName, action?, data, extraParams?) - Upload de arquivos
• postDownload(controllerName, action?, data, extraParams?) - Download de arquivos

Configuração e Autenticação

• getDecodedToken() - Decodificar token JWT do localStorage
• setAuthToken(token) - Configurar token de autorização
• removeAuthToken() - Remover token de autorização
• setHeader(key, value) - Configurar header global
• removeHeader(key) - Remover header
• httpClient - Instância do Axios configurada

Utilitários Adicionais

• retryRequest(requestFn, maxRetries?, delay?) - Retry automático de requisições
• createPaginationParams(page, limit) - Criar parâmetros de paginação
• parsePaginationResponse<T>(response) - Processar resposta paginada

Exemplos de Uso

import { get, post, put, del, upload, setAuthToken, getDecodedToken } from "@clube-certo/front-commons";

// Configurar autenticação
setAuthToken("seu-jwt-token");

// Obter dados decodificados do token
const userData = getDecodedToken();

// Requisições básicas
const users = await get("users");
const user = await get("users", "123");
const newUser = await post("users", "", { name: "João", email: "[email protected]" });
const updatedUser = await put("users", "123", { name: "João Silva" });
await del("users", "123");

// Requisições com parâmetros
const filteredUsers = await get("users", "", {
  page: 1,
  itensPerPage: 10,
  status: "active",
});

// Requisições com parâmetros customizados
const searchResults = await getQueryParams("search", "", [
  { key: "q", value: "termo de busca" },
  { key: "category", value: "produtos" },
]);

// Upload de arquivo
const formData = new FormData();
formData.append("file", file);
const uploadResult = await upload("files", "upload", formData);

// Download de arquivo
const blob = await postDownload("reports", "generate", {
  type: "pdf",
  filters: { startDate: "2023-01-01" },
});

// Retry automático
const dataWithRetry = await retryRequest(
  () => get("unstable-endpoint"),
  3, // máximo 3 tentativas
  1000 // delay de 1 segundo
);

Configuração de Ambiente

Configure a URL base da API através da variável de ambiente:

# .env
VITE_API_URL=https://api.exemplo.com/

Se não configurada, será usado http://localhost:3030/ por padrão.

Storage

• localStorage - Wrapper para localStorage
• sessionStorage - Wrapper para sessionStorage
• cookies - Utilitários para cookies
• MemoryCache - Cache em memória com TTL

Toast Notifications

A biblioteca inclui utilitários completos para exibição de notificações toast usando vue3-toastify:

• prepareToast(functionToCall, successMessage?, errorMessage?) - Executa função assíncrona com toasts automáticos
• errorToast(errorMessage?, description?) - Exibe toast de erro
• successToast(successMessage?, description?) - Exibe toast de sucesso
• infoToast(infoMessage?, description?) - Exibe toast informativo
• warningToast(warningMessage?, description?) - Exibe toast de aviso
• cn(...inputs) - Combina classes CSS usando clsx e tailwind-merge

Configuração dos Toasts

Para usar os toasts, configure o vue3-toastify em sua aplicação:

// main.ts
import { createApp } from "vue";
import Vue3Toastify, { type ToastContainerOptions } from "vue3-toastify";
import "vue3-toastify/dist/index.css";

const app = createApp(App);

app.use(Vue3Toastify, {
  autoClose: 3000,
  // outras opções...
} as ToastContainerOptions);

Exemplos de Uso dos Toasts

import { prepareToast, successToast, errorToast, warningToast, infoToast } from "@clube-certo/front-commons";

// Toast com função assíncrona
await prepareToast(() => api.saveData(data), "Dados salvos com sucesso!", "Erro ao salvar dados");

// Toasts simples
successToast("Operação realizada com sucesso!");
errorToast("Erro de validação", "O campo email é obrigatório");
warningToast("Sessão expirando", "Sua sessão expirará em 5 minutos");
infoToast("Nova funcionalidade", "Agora você pode exportar relatórios em PDF");

Schemas de Validação (Zod)

A biblioteca inclui schemas de validação pré-configurados usando Zod para validação de dados comuns:

• schemas.cpf - Validação de CPF brasileiro
• schemas.cnpj - Validação de CNPJ brasileiro
• schemas.email - Validação de email
• schemas.fullName - Validação de nome completo (mínimo 2 palavras)
• schemas.cep - Validação de CEP no formato 99.999-999
• schemas.celular - Validação de celular no formato (99)99999-9999
• schemas.creditCard - Validação de cartão de crédito
• schemas.senha - Validação de senha forte (8+ caracteres, maiúscula, minúscula, número, especial)
• schemas.url - Validação de URL (http/https)
• schemas.money - Validação de valor monetário (formato 123.45)
• schemas.date - Validação de data
• schemas.dateTime - Validação de data e hora (ISO 8601)
• schemas.calendar - Schema para datas de calendário

Exemplos de Uso dos Schemas

import { schemas } from "@clube-certo/front-commons";

// Validação de CPF
try {
  const cpf = schemas.cpf.parse("123.456.789-01");
  console.log("CPF válido:", cpf);
} catch (error) {
  console.error("CPF inválido:", error.message);
}

// Validação de email
const emailResult = schemas.email.safeParse("[email protected]");
if (emailResult.success) {
  console.log("Email válido:", emailResult.data);
} else {
  console.error("Email inválido:", emailResult.error.issues);
}

// Validação de senha
const senhaResult = schemas.senha.safeParse("MinhaSenh@123");
if (senhaResult.success) {
  console.log("Senha válida");
} else {
  console.error("Senha inválida:", senhaResult.error.issues[0].message);
}

// Validação de valor monetário
const valorResult = schemas.money.safeParse("1234.56");
if (valorResult.success) {
  console.log("Valor válido:", valorResult.data);
}

// Validação de nome completo
const nomeResult = schemas.fullName.safeParse("João Silva Santos");
if (nomeResult.success) {
  console.log("Nome válido:", nomeResult.data);
}

// Validação de CNPJ
const cnpjResult = schemas.cnpj.safeParse("12.345.678/0001-90");
if (cnpjResult.success) {
  console.log("CNPJ válido:", cnpjResult.data);
}

// Uso em formulários Vue com validação
import { z } from "zod";

const formSchema = z.object({
  nome: schemas.fullName,
  email: schemas.email,
  cpf: schemas.cpf,
  celular: schemas.celular,
  senha: schemas.senha,
  cep: schemas.cep,
  valorPedido: schemas.money,
});

// Validação de objeto completo
const dadosFormulario = {
  nome: "João Silva Santos",
  email: "[email protected]",
  cpf: "123.456.789-01",
  celular: "(11)99999-9999",
  senha: "MinhaSenh@123",
  cep: "01234-567",
  valorPedido: "150.00",
};

try {
  const dadosValidados = formSchema.parse(dadosFormulario);
  console.log("Formulário válido:", dadosValidados);
} catch (error) {
  console.error("Erros de validação:", error.issues);
}

Schemas Disponíveis

| Schema | Descrição | Formato Esperado | Exemplo | | ------------ | ------------------ | ------------------------------------------------ | --------------------------------- | | cpf | CPF brasileiro | Com ou sem máscara | "123.456.789-01" ou "12345678901" | | cnpj | CNPJ brasileiro | Com ou sem máscara | "12.345.678/0001-90" | | email | Email válido | Formato padrão | "[email protected]" | | fullName | Nome completo | Mínimo 2 palavras, 5 caracteres | "João Silva" | | cep | CEP brasileiro | Formato 99.999-999 | "01234-567" | | celular | Celular brasileiro | Formato (99)99999-9999 | "(11)99999-9999" | | creditCard | Cartão de crédito | 16 dígitos com ou sem traços | "1234-5678-9012-3456" | | senha | Senha forte | 8+ chars, maiúscula, minúscula, número, especial | "MinhaSenh@123" | | url | URL válida | Deve começar com http/https | "https://exemplo.com" | | money | Valor monetário | Formato decimal | "1234.56" | | date | Data válida | Qualquer formato de data válido | "2023-12-25" | | dateTime | Data e hora | Formato ISO 8601 | "2023-12-25T10:30:00Z" | | calendar | Data de calendário | Coerção para Date | Date object |

DOM

• querySelector() - Seletor de elementos
• createElement() - Criar elementos
• copyToClipboard() - Copiar para clipboard
• scrollToElement() - Scroll suave
• debounce() - Debounce de funções
• throttle() - Throttle de funções

Composables

useApi

const { data, loading, error, execute } = useApi("/api/endpoint");
const { post } = usePost("/api/create");
const { put } = usePut("/api/update");
const { remove } = useDelete("/api/delete");

useStorage

const [value, setValue] = useLocalStorage("key", defaultValue);
const [sessionValue, setSessionValue] = useSessionStorage("key", defaultValue);

useValidation

const { data, errors, isValid, validate } = useValidation(rules);

useDebounce

const debouncedValue = useDebounce(value, 500);
const debouncedFn = useDebouncedFunction(fn, 300);

useClipboard

const { copy, copied, isSupported } = useClipboard();

useDevice

const { deviceType, isMobile, isTablet, orientation } = useDevice();

🛠️ Desenvolvimento

Configuração do Ambiente

# Instalar dependências
npm install

# Executar em modo desenvolvimento
npm run dev

# Build da biblioteca
npm run build

# Executar testes
npm run test

# Lint do código
npm run lint

Estrutura do Projeto

src/
├── components/          # Componentes Vue
├── composables/         # Composables do Vue 3
├── utils/              # Funções utilitárias
│   ├── api.ts          # Utilitários de API
│   ├── dom.ts          # Utilitários DOM
│   ├── format.ts       # Formatação
│   ├── storage.ts      # Armazenamento
│   └── validation.ts   # Validação
├── types/              # Tipos TypeScript
└── index.ts            # Exportações principais

📦 Publicação no NPM

Pré-requisitos

Antes de publicar uma nova versão, certifique-se de estar logado no NPM:

# Login no NPM
npm login

# Credenciais:
# Username: clube-certo
# Password: [mesma senha da AWS]
# Email: [email associado à conta]

Processo de Publicação

1. Atualizar o código e fazer commit das alterações:

   git add .
   git commit -m "feat: descrição das alterações"
   git push origin main

2. Atualizar a versão no package.json:

   # Para patch (correções de bugs): 1.0.0 -> 1.0.1
   npm version patch
   
   # Para minor (novas funcionalidades): 1.0.0 -> 1.1.0
   npm version minor
   
   # Para major (breaking changes): 1.0.0 -> 2.0.0
   npm version major

3. Gerar o build da biblioteca:

   npm run build

4. Publicar no NPM:

   npm publish --access public

5. Fazer push da tag de versão:

   git push origin --tags

Verificação da Publicação

Após a publicação, você pode verificar se a nova versão está disponível:

# Verificar versões disponíveis
npm view @clube-certo/front-commons versions --json

# Verificar informações da versão atual
npm view @clube-certo/front-commons

Notas Importantes

• ⚠️ Sempre teste localmente antes de publicar uma nova versão
• 📋 Documente as alterações no commit e considere manter um CHANGELOG
• 🔄 Use versionamento semântico (SemVer) para as versões
• 🧪 Execute os testes antes da publicação: npm run test
• 🔍 Verifique o lint antes da publicação: npm run lint

📝 Contribuição

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/nova-feature)
3. Commit suas mudanças (git commit -am 'Adiciona nova feature')
4. Push para a branch (git push origin feature/nova-feature)
5. Abra um Pull Request

📄 Licença

MIT © Clube Certo

🔗 Links Úteis

• Vue 3 Documentation
• TypeScript Documentation
• Vitest Documentation