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:

  yarn dev

📌 Componente Autossuficiente

Este componente é totalmente autossuficiente e não requer nenhuma configuração adicional no projeto host:

• ✅ Fonte Montserrat: Carregada automaticamente pelo componente
• ✅ Estilos isolados: Não interferem com estilos do projeto host
• ✅ Zero dependências externas: Funciona out-of-the-box

Nota: A fonte Montserrat é carregada automaticamente do Google Fonts quando o componente é montado. Não é necessário adicionar nenhum link ou import no projeto host.

❌ 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:

import { MitreFormComponent } from "mitre-form-component";

// array de produtos 
const products = JSON.parse(process.env.VITE_PRODUCT_ID!);
// Exemplo de VITE_PRODUCT_ID: '[{"id":1,"name":"Apartamento 2 quartos"},{"id":2,"name":"Casa 3 quartos"}]'

<MitreFormComponent
  products={products}
  environment="prod"  //[Opcional] "staging" (padrão) | "prod". Define de onde sai apiUrl/apiToken/whatsappPhone/chatUrl (config interno).
  channel="form"  //[Opcional] "form" (padrão) | "chat" | "whatsapp". Ver "🔀 Modos de submit (channel)".
  showHeader={true}  //[Opcional] Se irá exibir ou não o cabeçalho
  title="Atendimento por mensagem"  //[Opcional] Título do formulário (ignorado em channel=whatsapp/chat)
  subtitle="Informe seus dados e retornaremos a mensagem."  //[Opcional] Subtítulo (ignorado em channel=whatsapp/chat)
  backgroundColor="#000"  //[Opcional] 
  textColor="#ffffff"  //[Opcional] 
  buttonBackgroundColor="#FF5733"  //[Opcional]
  buttonTextColor="#FFF"  //[Opcional]
  innerPadding="0.2rem"  //[Opcional]
  inputBackgroundColor="#000"  //[Opcional]
  inputBorderColor="#000"  //[Opcional]
  inputFocusBorderColor="#76B"  //[Opcional]
  inputPlaceholderColor="#FFF"  //[Opcional]
  inputTextColor="#FFF"  //[Opcional]
  showContactPreference={true}  //[Opcional] Exibe campo de preferência de contato (ignorado em channel=whatsapp/chat)
  // idProdutoTerceiro={produto.idTerceiro}  //[Opcional, quando channel !== "form"]
  // idEmpreendimento={produto.id}  //[Opcional, quando channel !== "form"]
  // naoCriarEvento={false}  //[Opcional] Override do default (que é true em chat/whatsapp).
  onSuccess={(requestBody, leadId) => console.log('Formulário enviado com sucesso!', requestBody, leadId)}  //[Opcional] Callback de sucesso, útil para tracking
  onError={(error) => console.error('Erro ao enviar formulário:', error)}  //[Opcional] Callback de erro
/>;

🛠️ Tecnologias utilizadas

• React
• React Hook Form
• Yup
• Styled Components
• Polished
• React Icons
• React Internation Phone
• Vite
• Tsup

🎨 Estilos Isolados

Este componente não injeta estilos globais no projeto host, evitando conflitos de CSS. Todos os estilos são aplicados de forma isolada usando styled-components, garantindo que:

• ✅ Não há poluição do escopo global com variáveis CSS
• ✅ Não há conflitos com classes utilitárias
• ✅ Não há reset CSS que afete o projeto host
• ✅ Fonte Montserrat carregada automaticamente (não afeta outros componentes)
• ✅ O componente pode ser usado em qualquer projeto React sem efeitos colaterais ou configurações adicionais

⚙️ Instalação

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

# Usando npm
npm install mitre-form-component

# Usando yarn
yarn add mitre-form-component

# Usando pnpm
pnpm add mitre-form-component

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
• environment (opcional, "staging" | "prod"): Define de qual config interno o componente lê apiUrl, apiToken, whatsappPhone e chatUrl. Padrão: "staging". Ver §"🌐 Environment".
• showHeader (opcional, boolean): Controla se o cabeçalho será mostrado. Padrão: true.
• title (opcional, string): Título do formulário. Padrão: "Atendimento por mensagem". Quando channel="whatsapp" esta prop é ignorada e o título é forçado para "Fale com um corretor por WhatsApp"; quando channel="chat" é forçado para "Fale com um corretor por chat" (ver §"Modos de submit").
• subtitle (opcional, string): Subtítulo do formulário. Padrão: "Informe seus dados e retornaremos a mensagem.". Quando channel="whatsapp" ou channel="chat" esta prop é ignorada e o subtítulo é forçado para "Informe seus dados para contato." (ver §"Modos de submit").
• 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.
• showContactPreference (opcional, boolean): Exibe um campo de seleção "Preferência de Contato" com as opções Whatsapp, Email e Ligação. Quando selecionado, o valor é enviado à API como preferencia_contato. Padrão: false. Quando channel="whatsapp" esta prop é ignorada e tratada como false, e o componente injeta preferencia_contato: "Whatsapp" automaticamente no body do POST (ver §"Modos de submit").
• channel (opcional, "form" | "chat" | "whatsapp"): Define o comportamento do submit. "form" (padrão) preserva o comportamento histórico (apenas POST /leads). "chat" e "whatsapp" continuam fazendo o POST /leads e, em sucesso, abrem o atendimento em nova aba. Ver seção "🔀 Modos de submit (channel)" abaixo. Padrão: "form".
• idProdutoTerceiro (opcional, string | number): Repassado no body do POST /leads e no virtual_obj (modo chat) quando channel !== "form".
• idEmpreendimento (opcional, string | number): Repassado no body do POST /leads e no virtual_obj (modo chat) quando channel !== "form".
• naoCriarEvento (opcional, boolean): Se true, envia naoCriarEvento: true no body do POST /leads (e no virtual_obj no modo chat) para instruir o CRM a não criar evento associado ao lead. Default automático: true quando channel === "chat" ou channel === "whatsapp" (paridade com o fluxo antigo do atendimento.html); false quando channel === "form". Passe false explicitamente para forçar a criação do evento mesmo em chat/whatsapp.
• onSuccess (opcional, função): Callback executado quando o POST /leads retorna sucesso, em qualquer channel. Recebe (requestBody, leadId). Útil para tracking (GTM, Analytics), redirect customizado ou logging. O componente continua exibindo a UI de sucesso (mensagem em channel=form, modal em channel=whatsapp/channel=chat) independente do callback.
• onError (opcional, função): Callback executado quando o POST /leads falha. Recebe Error. Útil para tracking de erro (Sentry, Datadog, GTM). O componente continua exibindo a UI de erro independente do callback.

🎯 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:

interface Product {
  id: number;    // ID único do produto
  name: string;  // Nome do produto para exibição
}

📞 Preferência de Contato

Quando showContactPreference={true}, um campo de seleção é exibido no formulário com as seguintes opções:

| Valor do enum | Valor enviado à API | |--------------------------|---------------------| | ContactPreference.Whatsapp | "Whatsapp" | | ContactPreference.Email | "Email" | | ContactPreference.Ligacao | "Ligação" |

O campo é opcional: se o usuário não selecionar nenhuma opção, preferencia_contato não é enviado no body da requisição.

O enum ContactPreference é exportado pela biblioteca para uso externo, se necessário:

import { MitreFormComponent, ContactPreference } from "mitre-form-component";

<MitreFormComponent
  products={products}
  environment="prod"
  showContactPreference={true}
/>

🌐 Environment

A partir da v2.0, o componente gerencia internamente apiUrl, apiToken, whatsappPhone e chatUrl. A landing não passa mais essas props — apenas escolhe o environment:

<MitreFormComponent products={products} environment="prod" />  // produção
<MitreFormComponent products={products} environment="staging" /> // staging/homologação (padrão)

Os valores de cada environment vivem em src/config/environments.ts. Mudanças nessas URLs/tokens exigem nova versão da lib publicada no npm e atualização das landings consumidoras.

| Environment | apiUrl | chatUrl | |---|---|---| | "staging" | https://leads-hml.mitrerealty.com.br/api-leads | https://crm-hml.mitrerealty.com.br/wcc/UserLoginSubmit.do | | "prod" | https://leads.mitrerealty.com.br/api-leads | https://crm.mitrerealty.com.br/wcc/UserLoginSubmit.do |

Se environment for um valor desconhecido ou se os campos resolvidos vierem vazios, o componente exibe a tela genérica de erro ("Erro no carregamento do formulário!") no lugar do form.

🔀 Modos de submit (channel)

Por padrão (channel="form"), ao enviar o formulário o componente faz apenas o POST /leads e exibe uma mensagem de sucesso — o consumidor continua na mesma página. Esse é o comportamento histórico e segue inalterado para todos os usos atuais.

Para casos em que, após salvar o lead, o usuário precisa ser direcionado para um channel de atendimento (chat ou WhatsApp), o componente expõe a prop channel com mais dois modos: "chat" e "whatsapp". Nesses dois modos:

• O POST /leads é feito normalmente.
• Em sucesso, é exibido um modal de confirmação ("Cadastro realizado! Clique abaixo para continuar...") e o clique no botão do modal abre o atendimento em uma nova aba, mantendo a landing page do consumidor aberta.
• Em caso de falha no POST /leads, é exibido um modal de erro ("Não foi possível completar seu contato.") e a segunda aba não é aberta.
• O número do WhatsApp e a URL do chat vêm da config interna do environment selecionado — não precisam ser passados como props.

O tipo Channel é exportado pela biblioteca:

import { MitreFormComponent, type Channel } from "mitre-form-component";

Modo "chat"

Após salvar o lead, o botão do modal de sucesso submete (em nova aba) um POST application/x-www-form-urlencoded para a chatUrl do environment, com um único campo virtual_obj contendo o JSON do lead acrescido de externalOriginId, pagina, idProdutoTerceiro/idEmpreendimento (se informados) e naoCriarEvento (quando o flag efetivo é true).

<MitreFormComponent
  products={products}
  environment="prod"
  channel="chat"
  idProdutoTerceiro={produto.idTerceiro}
  idEmpreendimento={produto.id}
/>

Modo "whatsapp"

Após salvar o lead, o botão do modal de sucesso abre https://api.whatsapp.com/send?phone=<whatsappPhone>&text=... em nova aba. A mensagem pré-preenchida é fixa: "Olá! Tenho interesse e gostaria de mais informações.".

<MitreFormComponent
  products={products}
  environment="prod"
  channel="whatsapp"
/>

Campos extras enviados ao /leads

Quando channel !== "form", o componente injeta automaticamente os seguintes campos no body do POST /leads:

| Campo | Quando | Origem | |---|---|---| | channel | sempre que channel !== "form" | valor da prop | | pagina | sempre que channel !== "form" | window.location.href no momento do submit | | is_chat | sempre que channel !== "form" (paridade com atendimento.html legado) | constante true | | idProdutoTerceiro | se a prop foi informada | valor da prop | | idEmpreendimento | se a prop foi informada | valor da prop | | naoCriarEvento | quando o flag efetivo é true (default em chat/whatsapp; ver prop naoCriarEvento) | constante true | | preferencia_contato | apenas em channel === "whatsapp" | constante "Whatsapp" (em channel === "whatsapp" e channel === "chat" a prop showContactPreference é ignorada e o select não é exibido) |

Esses campos são aceitos pelo backend api-leads sem nenhuma alteração — o LeadDTO possui @JsonAlias para os campos conhecidos e @JsonAnySetter para o restante.

Textos fixos em channel="whatsapp" e channel="chat"

Quando channel="whatsapp" ou channel="chat", os seguintes textos do formulário são forçados, independente das props passadas:

| Elemento | channel="whatsapp" | channel="chat" | |---|---|---| | Título (prop title) | "Fale com um corretor por WhatsApp" | "Fale com um corretor por chat" | | Subtítulo (prop subtitle) | "Informe seus dados para contato." | "Informe seus dados para contato." | | Texto do botão de submit | "Entrar" | "Entrar" |

Paridade com o fluxo legado atendimento.html (título e botão), com subtítulo unificado entre os canais.

Validações

Em render-time o componente valida:

• Environment: se a prop environment for desconhecida, ou se a config interna resolvida não tiver apiUrl/apiToken → tela genérica de erro.
• channel=chat: a chatUrl do environment precisa ser URL absoluta com protocolo http(s); caso contrário, tela genérica de erro.
• channel=whatsapp: o whatsappPhone do environment precisa ser número válido segundo google-libphonenumber; caso contrário, tela genérica de erro.

Todas essas validações rodam antes do submit e substituem a renderização do formulário pela tela "Erro no carregamento do formulário!" + console.error técnico.

🚨 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:

import dynamic from "next/dynamic";

import { ErrorBoundary } from "react-error-boundary";
const MitreFormComponent = dynamic(
  () =>
    import("mitre-form-component").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" }
    ]}
    environment="prod"
  />
</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:

yarn build

3. Publicar no npm:

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.