mitre-form-component/README.md

Componente de formulário de captação de leads para ser usado em projetos da Mitre Realty.

# Mitre Form Component

Componente de formulário de captação de leads para ser usado em projetos da Mitre Realty. Esta biblioteca oferece um componente pronto para facilitar a implementação de formulários em suas páginas, com validação e integração com APIs para registro de leads.

## 🚨 Avisos importantes

Este projeto foi desenvolvido para ser usado diretamente em projetos da Mitre Realty. Algumas partes da biblioteca são essenciais e **não devem ser alteradas ou removidas**.

- **Exemplo de uso**: Dentro de `src/app/page.tsx`, há um exemplo de uso do componente, disponível apenas para visualização. Para executar e ver o exemplo em funcionamento, execute o comando:

  ```bash
  yarn dev
  ```

---

## ❌ Itens que NÃO devem ser modificados

### **Código do componente**

- O comportamento básico do componente, como a integração com a API e as interações de formulário, **não devem ser alterados**.

### **Dependências**

- Certifique-se de que as dependências do `package.json` estão intactas para garantir o funcionamento correto da biblioteca. Alterações nas versões podem causar incompatibilidade com o sistema.

---

## ✅ Itens que DEVEM ser modificados

### 1. **Configuração do Componente**

Embora o componente esteja pronto para uso, você pode personalizá-lo ao passar as props adequadas.

### 2. **Componente `MitreFormComponent`**

Aqui está um exemplo de uso básico dentro do projeto:

```tsx
import { MitreFormComponent } from "mitre-form-component-next";

// Definir array de produtos (pode vir de variável de ambiente)
const products = JSON.parse(process.env.VITE_PRODUCTS!);
// Exemplo de VITE_PRODUCTS: '[{"id":1,"name":"Apartamento 2 quartos"},{"id":2,"name":"Casa 3 quartos"}]'

<MitreFormComponent
  products={products}
  apiUrl={process.env.VITE_REGISTER_LEADS_URL!}
  apiToken={process.env.VITE_REGISTER_LEADS_TOKEN!}
  showHeader={true}  //[Opcional] Se irá exibir ou não o cabeçalho com "Atendimento por Mensagem - Informe seus dados e retornaremos a mensagem."
  backgroundColor="#000"  //[Opcional] 
  textColor="#ffffff"  //[Opcional] 
  buttonBackgroundColor="#FF5733"
  buttonTextColor="#FFF" // [Opcional]
  innerPadding="0.2rem"  //[Opcional]
  inputBackgroundColor="#000"  //[Opcional]
  inputBorderColor="#000"  //[Opcional]
  inputFocusBorderColor="#76B"  //[Opcional]
  inputPlaceholderColor="#FFF" //[Opcional]
  inputTextColor="#FFF"  //[Opcional]
/>;
```

---

## 🛠️ Tecnologias utilizadas

- [React](https://react.dev/)
- [React Hook Form](https://react-hook-form.com/)
- [Yup](https://github.com/jquense/yup)
- [Styled Components](https://styled-components.com/)
- [Polished](https://polished.js.org/)
- [React Icons](https://react-icons.github.io/react-icons/)
- [React Internation Phone](https://github.com/ybrusentsov/react-international-phone)
- [Vite](https://vitejs.dev/)
- [Tsup](https://tsup.egoist.dev/)

---

## ⚙️ Instalação

Este componente pode ser instalado em qualquer projeto React usando o gerenciador de pacotes de sua preferência (npm, yarn, pnpm, etc.).

```bash
# Usando npm
npm install mitre-form-component-next

# Usando yarn
yarn add mitre-form-component-next

# Usando pnpm
pnpm add mitre-form-component-next
```

Depois de instalar a biblioteca, você pode começar a usá-la diretamente no seu projeto.

---

## 🔧 Props do Componente

O `MitreFormComponent` aceita as seguintes props:

- **`products`** (array): Array de objetos contendo os produtos disponíveis. Cada produto deve ter `id` (number) e `name` (string).
  - Se o array contém apenas 1 produto: o formulário usa automaticamente esse produto
  - Se o array contém múltiplos produtos: é exibido um seletor para o usuário escolher
- **`apiUrl`** (string): URL da API para registro dos leads.
- **`apiToken`** (string): Token de autenticação da API.
- **`showHeader`** (opcional, boolean): Controla se o cabeçalho será mostrado. Padrão: `false`.
- **`backgroundColor`** (opcional, string): Cor de fundo do formulário. Padrão: `#CECECE`.
- **`textColor`** (opcional, string): Cor dos textos do cabeçalho, do label dos inputs e do texto de privacidade. Padrão: `#2F2F2F`.
- **`buttonBackgroundColor`** (opcional, string): Define a cor de fundo do botão. Padrão: `#F6C76B`.
- **`buttonTextColor`** (opcional, string): Define a cor do texto do botão. Padrão: `#2F2F2F`.
- **`innerPadding`** (opcional, string): Espaçamento interno do componente com relação às bordas. Padrão `1rem`.
- **`inputBackgroundColor`** (opcional, string): Cor de fundo do input. Padrão: `#FFF`.
- **`inputBorderColor`** (opcional, string): Cor da borda do input. Padrão: `transparent`.
- **`inputFocusBorderColor`** (opcional, string): Cor da borda do input quando selecionado. Padrão: `#F6C76B`.
- **`inputPlaceholderColor`** (opcional, string): Cor do placeholder do input. Padrão: `#B6B6B6`.
- **`inputTextColor`** (opcional, string): Cor do texto do input. Padrão: `#2F2F2F`.

---

## 🎯 Comportamento dos Produtos

O componente possui comportamento inteligente baseado na quantidade de produtos fornecidos:

### **Array com 1 produto:**
- O formulário usa automaticamente o único produto disponível
- Não é exibido seletor de produto
- O usuário preenche apenas nome, email e telefone

### **Array com múltiplos produtos:**
- É exibido um campo de seleção "Produto de interesse" antes do campo nome
- O usuário deve selecionar um produto para prosseguir
- Validação obrigatória da seleção de produto

### **Array inválido (vazio, nulo, etc.):**
- É exibida uma mensagem de erro no lugar do formulário
- O erro é logado no console para debug
- Mensagem amigável: "Erro no carregamento do formulário!"

### **Estrutura do objeto Product:**
```typescript
interface Product {
  id: number;    // ID único do produto
  name: string;  // Nome do produto para exibição
}
```

---

## 🚨 Componente dentro de um `ErrorBoundary`

Recomendamos que o componente `MitreFormComponent` seja sempre utilizado dentro de um `ErrorBoundary` para garantir que a aplicação não quebre em caso de falha no carregamento do componente. Também é preciso usar dynamic do next/dynamics para a importação.

Exemplo de uso básico como biblioteca em projetos Nextjs externos:

```tsx
import dynamic from "next/dynamic";

import { ErrorBoundary } from "react-error-boundary";
const MitreFormComponent = dynamic(
  () =>
    import("mitre-form-component-next").then((mod) => mod.MitreFormComponent),
  { ssr: false }
);

<ErrorBoundary fallback={<div>Erro ao carregar o formulário</div>}>
  <MitreFormComponent
    products={[
      { id: 1, name: "Apartamento 2 quartos" },
      { id: 2, name: "Casa 3 quartos" }
    ]}
    apiUrl={process.env.NEXT_PUBLIC_REGISTER_LEADS_URL!}
    apiToken={process.env.NEXT_PUBLIC_REGISTER_LEADS_TOKEN!}
  />
</ErrorBoundary>;
```

Para uso em outros frameworks, fazer o import básico conforme Artigo 2

---

## 🏗️ Como gerar o build e publicar no npm

Para gerar o build da biblioteca e publicá-la no npm, siga estas etapas:

1. **Incrementar a versão no `package.json`**:
   No arquivo `package.json`, atualize a versão da biblioteca.

2. **Executar o build**:

```bash
yarn build
```

3. **Publicar no npm**:

```bash
yarn publish --new-version 0.x.xxx
```

---

## 📄 Licença

Este projeto é mantido pela **Mitre Realty**. Uso restrito aos colaboradores e parceiros autorizados.

---

## 🧑‍💻 Contato

Para dúvidas ou suporte sobre o uso desta biblioteca, entre em contato com o time de desenvolvimento interno da **Mitre Realty**.

---

> Mitre Realty © Todos os direitos reservados.