Package Exports

cep-search-lib
cep-search-lib/index.ts

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (cep-search-lib) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Sumário

Instalação e Configuração
Dependências
useCep Hook - Documentação
- Exemplo de uso
- Retornos
CepSearch Component - Documentação

Instalação e Configuração

Esta biblioteca foi desenvolvida para facilitar a busca de endereços a partir de CEPs brasileiros, utilizando a API pública do ViaCEP. Ela oferece dois recursos principais: um Hook chamado useCep e um componente React chamado CepSearch. Vamos mostrar como instalar e configurar essa biblioteca.

Pré-requisitos

Antes de instalar, verifique se você já possui um projeto React configurado. Se ainda não, siga os passos para criar um projeto básico usando create-react-app:

npx create-react-app meu-projeto
cd meu-projeto

Instalação

Para instalar a biblioteca, basta rodar o seguinte comando:

npm install cep-search-lib

Isso adicionará todos os arquivos e dependências necessárias ao seu projeto.

Feats Implementadas

Atualmente, esta biblioteca possui duas funcionalidades principais, que facilitam a integração com a API ViaCEP:

useCep: Um Hook customizado que permite fazer buscas de endereço a partir de um CEP informado pelo usuário. CepSearch: Um componente que utiliza o useCep para fornecer uma interface completa de busca de endereços, com campo de entrada e botão de ação.

Agora que você instalou a biblioteca, veja abaixo os detalhes de uso para cada funcionalidade implementada.

Dependências

Esta biblioteca utiliza as seguintes versões de dependências para garantir a compatibilidade e o funcionamento correto:

{
  "@mui/material": "^6.1.3",
  "@mui/system": "^6.1.3",
  "next": "^14.2.15",
  "react": "^18.3.1",
  "react-toastify": "^10.0.5"
}

useCep Hook - Documentação

O useCep é um Hook customizado desenvolvido para facilitar a busca de endereços no Brasil, utilizando a API pública do ViaCEP. Com ele, é possível obter dados completos de um endereço, como logradouro, bairro, cidade e estado, a partir de um CEP informado. Que roda do lado do cliente

Exemplo de uso

import React from 'react';
import { useCep } from 'cep-search-lib';

const SimpleCepLogger = () => {
  const { cep, setCep, fetchEndereco } = useCep();

  const handleFetch = () => {
    fetchEndereco(); // Aciona a busca do endereço
    console.log('CEP atual:', cep);
  };

  return (
    <div>
      <input
        type="text"
        value={cep}
        onChange={(e) => setCep(e.target.value)}
        placeholder="Digite o CEP"
      />
      <button onClick={handleFetch}>Buscar</button>
    </div>
  );
};

export default SimpleCepLogger;

Retornos

const { cep, setCep, endereco, fetchEndereco } = useCep();

cep

Estado que armazena o valor atual do CEP inserido.

setCep

Função responsável por atualizar o estado do cep.

endereco

Objeto que contém a resposta da API ViaCEP com os dados do endereço.

interface cepResponse {
  cep: string;
  logradouro: string;
  complemento: string;
  unidade: string;
  bairro: string;
  localidade: string;
  uf: string;
  estado: string;
  regiao: string;
  ibge: string;
  gia: string;
  ddd: string;
  siafi: string;
  erro: boolean;
}

fetchEndereco

Função que aciona a busca do endereço com base no CEP informado.

tratamentos de erros

O Hook lida com diferentes tipos de erros, exibindo mensagens apropriadas através de um toast (opcionalmente). Você pode controlar a exibição dessas mensagens utilizando a flag handleToasts.

Utilizando a flag handleToasts

handleToasts: true (padrão): Exibe mensagens de erro e sucesso utilizando toasts.
handleToasts: false (padrão): Não exibe toasts. O controle das mensagens é de sua responsabilidadew.

casos de erros

1. CEP inválido ou formato incorreto

Motivo do erro: O usuário inseriu um CEP que não tem 8 dígitos ou contém caracteres que não são numéricos.

Mensagem no toast: "Por favor, insira um CEP válido com 8 dígitos numéricos."

Esse erro ocorre porque o CEP deve ter exatamente 8 dígitos numéricos. O código verifica se o valor inserido atende a esses critérios e, caso contrário, a busca nem é realizada.

2. CEP não encontrado

Motivo do erro: O CEP informado é válido, mas não está registrado no ViaCEP.

Mensagem no toast: "CEP não encontrado. Por favor, insira um CEP válido."

Esse erro ocorre quando a API do ViaCEP retorna a chave erro: true, indicando que o CEP não foi encontrado na base de dados. Isso pode acontecer quando o CEP é inexistente ou está incorreto.

3. Erro na requisição ou problema na API

Motivo do erro: Houve algum problema com a requisição, como falha de conexão, erro no servidor, ou algum outro problema inesperado.

Mensagem no toast: "Houve um problema ao buscar o endereço."

CepSearch Component - Documentação

O CepSearch é um componente React que utiliza o Hook customizado useCep para permitir que os usuários busquem endereços a partir de um CEP. Ele fornece uma interface simples, onde o usuário pode digitar um CEP e visualizar os dados do endereço correspondente.

Exemplo de Uso

Para utilizar o componente CepSearch, você deve importá-lo em seu arquivo e incluí-lo na sua árvore de componentes.

import React from 'react';
import { CepSearch } from 'cep-search-lib';

const BuscaEndereco = () => {
  return (
    <div>
      <h1>Buscar Endereço pelo CEP</h1>
      <CepSearch 
        label="Digite o CEP"
        buttonLabel="Buscar"
        inputVariant="outlined"
        buttonVariant="contained"
        buttonColor="primary"
      />
    </div>
  );
};

export default BuscaEndereco;

Estrutura Visual do Componente

Ao renderizar o componente CepSearch, os seguintes elementos aparecerão na tela em ordem:

TextField (Campo de Entrada):
- Descrição: Um campo de entrada onde o usuário pode digitar o CEP.
O TextField é exibido no topo, ocupando toda a largura disponível e com margens para melhor espaçamento.
Button (Botão de Busca):
- Descrição: Um botão que aciona a busca pelo endereço quando clicado.
O botão é exibido logo abaixo do campo de entrada, com um estilo destacado que o torna fácil de identificar e acessar.
Box (Container para Resultados):
- Descrição: Um contêiner que é renderizado condicionalmente, contendo as informações do endereço, se disponíveis.
Dentro do Box, os seguintes elementos são exibidos, um por um, caso o endereco.logradouro esteja presente:
- Typography (Exibição de Rua):
  - Texto: "Rua: {endereco.logradouro}"
- Typography (Exibição de Unidade):
  - Texto: "Unidade: {endereco.unidade}"
- Typography (Exibição de Bairro):
  - Texto: "Bairro: {endereco.bairro}"
- Typography (Exibição de Cidade):
  - Texto: "Cidade: {endereco.localidade}"
- Typography (Exibição de Estado):
  - Texto: "Estado: {endereco.uf}"
- Typography (Exibição de Região):
  - Texto: "Região: {endereco.regiao}"
- Typography (Exibição de DDD):
  - Texto: "DDD: {endereco.ddd}"

Propriedades (`cepComponentProps`)

O componente CepSearch aceita várias propriedades que permitem personalizar tanto o comportamento quanto a aparência do componente.

Propriedades disponíveis:

label (string)
Texto exibido como rótulo do campo de entrada de CEP.
- Default: "Digite o CEP"
buttonLabel (string)
Texto exibido no botão de busca.
- Default: "Buscar"
inputVariant ("outlined" | "filled" | "standard")
Define o estilo visual do campo de entrada.
- Default: "outlined"
buttonColor ("primary" | "secondary")
Cor do botão de busca.
- Default: "primary"
buttonVariant ("outlined" | "contained" | "text")
Variante do botão, alterando seu estilo visual.
- Default: "contained"
buttonFullWidth (boolean)
Define se o botão ocupará toda a largura disponível.
- Default: false
containerSx (SxProps)
Propriedades de estilo personalizadas para o contêiner do componente.
inputSx (SxProps)
Propriedades de estilo personalizadas para o campo de entrada.
buttonSx (SxProps)
Propriedades de estilo personalizadas para o botão de busca.

cep-search-lib