mitre-form-component 0.1.3 → 2.0.0

package/README.md

@@ -47,7 +47,7 @@ Embora o componente esteja pronto para uso, você pode personalizá-lo ao passar
 Aqui está um exemplo de uso básico dentro do projeto:
 
 ```tsx
-import { MitreFormComponent } from "mitre-form-component-next";
+import { MitreFormComponent } from "mitre-form-component";
 
 // array de produtos 
 const products = JSON.parse(process.env.VITE_PRODUCT_ID!);
@@ -55,11 +55,11 @@ const products = JSON.parse(process.env.VITE_PRODUCT_ID!);
 
 <MitreFormComponent
   products={products}
-  apiUrl={process.env.VITE_REGISTER_LEADS_URL!}
-  apiToken={process.env.VITE_REGISTER_LEADS_TOKEN!}
+  ambiente="prod"  //[Opcional] "homol" (padrão) | "prod". Define de onde sai apiUrl/apiToken/whatsappPhone/chatUrl (config interno).
+  canal="form"  //[Opcional] "form" (padrão) | "chat" | "whatsapp". Ver "🔀 Modos de submit (canal)".
   showHeader={true}  //[Opcional] Se irá exibir ou não o cabeçalho
-  title="Atendimento por mensagem"  //[Opcional] Título do formulário
-  subtitle="Informe seus dados e retornaremos a mensagem."  //[Opcional] Subtítulo do formulário
+  title="Atendimento por mensagem"  //[Opcional] Título do formulário (ignorado em canal=whatsapp/chat)
+  subtitle="Informe seus dados e retornaremos a mensagem."  //[Opcional] Subtítulo (ignorado em canal=whatsapp/chat)
   backgroundColor="#000"  //[Opcional] 
   textColor="#ffffff"  //[Opcional] 
   buttonBackgroundColor="#FF5733"  //[Opcional]
@@ -70,8 +70,10 @@ const products = JSON.parse(process.env.VITE_PRODUCT_ID!);
   inputFocusBorderColor="#76B"  //[Opcional]
   inputPlaceholderColor="#FFF"  //[Opcional]
   inputTextColor="#FFF"  //[Opcional]
-  onSuccess={(requestBody, leadId) => console.log('Formulário enviado com sucesso!', requestBody, leadId)}  //[Opcional]
-  onError={(error) => console.error('Erro ao enviar formulário:', error)}  //[Opcional]
+  showPreferenciaContato={true}  //[Opcional] Exibe campo de preferência de contato (ignorado em canal=whatsapp/chat)
+  // idProdutoTerceiro={produto.idTerceiro}  //[Opcional, quando canal !== "form"]
+  // idEmpreendimento={produto.id}  //[Opcional, quando canal !== "form"]
+  // naoCriarEvento={false}  //[Opcional] Override do default (que é true em chat/whatsapp).
 />;
 ```
 
@@ -107,13 +109,13 @@ Este componente pode ser instalado em qualquer projeto React usando o gerenciado
 
 ```bash
 # Usando npm
-npm install mitre-form-component-next
+npm install mitre-form-component
 
 # Usando yarn
-yarn add mitre-form-component-next
+yarn add mitre-form-component
 
 # Usando pnpm
-pnpm add mitre-form-component-next
+pnpm add mitre-form-component
 ```
 
 Depois de instalar a biblioteca, você pode começar a usá-la diretamente no seu projeto.
@@ -127,11 +129,10 @@ 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.
+- **`ambiente`** (opcional, `"homol" | "prod"`): Define de qual config interno o componente lê `apiUrl`, `apiToken`, `whatsappPhone` e `chatUrl`. Padrão: `"homol"`. Ver §"🌐 Ambiente".
 - **`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"`.
-- **`subtitle`** (opcional, string): Subtítulo do formulário. Padrão: `"Informe seus dados e retornaremos a mensagem."`.
+- **`title`** (opcional, string): Título do formulário. Padrão: `"Atendimento por mensagem"`. **Quando `canal="whatsapp"` esta prop é ignorada e o título é forçado para `"Fale com um corretor por WhatsApp"`; quando `canal="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 `canal="whatsapp"` ou `canal="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`.
@@ -142,8 +143,11 @@ O `MitreFormComponent` aceita as seguintes props:
 - **`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`.
-- **`onSuccess`** (opcional, função): Callback executado quando o formulário é enviado com sucesso. Recebe dois parâmetros: `requestBody` (objeto com os dados enviados) e `leadId` (string com o ID do lead retornado pela API).
-- **`onError`** (opcional, função): Callback executado quando ocorre um erro no envio do formulário. Recebe um objeto `Error` como parâmetro.
+- **`showPreferenciaContato`** (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 `canal="whatsapp"` esta prop é ignorada e tratada como `false`**, e o componente injeta `preferencia_contato: "Whatsapp"` automaticamente no body do POST (ver §"Modos de submit").
+- **`canal`** (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 (`canal`)" abaixo. Padrão: `"form"`.
+- **`idProdutoTerceiro`** (opcional, `string | number`): Repassado no body do POST `/leads` e no `virtual_obj` (modo chat) quando `canal !== "form"`.
+- **`idEmpreendimento`** (opcional, `string | number`): Repassado no body do POST `/leads` e no `virtual_obj` (modo chat) quando `canal !== "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 `canal === "chat"` ou `canal === "whatsapp"` (paridade com o fluxo antigo do `atendimento.html`); `false` quando `canal === "form"`. Passe `false` explicitamente para forçar a criação do evento mesmo em chat/whatsapp.
 
 ---
 
@@ -176,6 +180,135 @@ interface Product {
 
 ---
 
+## 📞 Preferência de Contato
+
+Quando `showPreferenciaContato={true}`, um campo de seleção é exibido no formulário com as seguintes opções:
+
+| Valor do enum            | Valor enviado à API |
+|--------------------------|---------------------|
+| `PreferenciaContato.Whatsapp` | `"Whatsapp"`   |
+| `PreferenciaContato.Email`    | `"Email"`      |
+| `PreferenciaContato.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 `PreferenciaContato` é exportado pela biblioteca para uso externo, se necessário:
+
+```tsx
+import { MitreFormComponent, PreferenciaContato } from "mitre-form-component";
+
+<MitreFormComponent
+  products={products}
+  ambiente="prod"
+  showPreferenciaContato={true}
+/>
+```
+
+---
+
+## 🌐 Ambiente
+
+A partir da v1.0, o componente gerencia internamente `apiUrl`, `apiToken`, `whatsappPhone` e `chatUrl`. A landing **não passa mais essas props** — apenas escolhe o ambiente:
+
+```tsx
+<MitreFormComponent products={products} ambiente="prod" />  // produção
+<MitreFormComponent products={products} ambiente="homol" /> // homologação (padrão)
+```
+
+Os valores de cada ambiente 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.
+
+| Ambiente | apiUrl | chatUrl |
+|---|---|---|
+| `"homol"` | `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 `ambiente` 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 (`canal`)
+
+Por padrão (`canal="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 canal de atendimento (chat ou WhatsApp), o componente expõe a prop `canal` 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 `ambiente` selecionado — não precisam ser passados como props.
+
+O tipo `Canal` é exportado pela biblioteca:
+
+```tsx
+import { MitreFormComponent, type Canal } 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 ambiente, 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`).
+
+```tsx
+<MitreFormComponent
+  products={products}
+  ambiente="prod"
+  canal="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."`.
+
+```tsx
+<MitreFormComponent
+  products={products}
+  ambiente="prod"
+  canal="whatsapp"
+/>
+```
+
+### Campos extras enviados ao `/leads`
+
+Quando `canal !== "form"`, o componente injeta automaticamente os seguintes campos no body do `POST /leads`:
+
+| Campo | Quando | Origem |
+|---|---|---|
+| `canal` | sempre que `canal !== "form"` | valor da prop |
+| `pagina` | sempre que `canal !== "form"` | `window.location.href` no momento do submit |
+| `is_chat` | sempre que `canal !== "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 `canal === "whatsapp"` | constante `"Whatsapp"` (em `canal === "whatsapp"` e `canal === "chat"` a prop `showPreferenciaContato` é 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 `canal="whatsapp"` e `canal="chat"`
+
+Quando `canal="whatsapp"` ou `canal="chat"`, os seguintes textos do formulário são forçados, independente das props passadas:
+
+| Elemento | `canal="whatsapp"` | `canal="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:
+
+- **Ambiente**: se a prop `ambiente` for desconhecida, ou se a config interna resolvida não tiver `apiUrl`/`apiToken` → tela genérica de erro.
+- **canal=chat**: a `chatUrl` do ambiente precisa ser URL absoluta com protocolo `http(s)`; caso contrário, tela genérica de erro.
+- **canal=whatsapp**: o `whatsappPhone` do ambiente 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.
@@ -188,7 +321,7 @@ import dynamic from "next/dynamic";
 import { ErrorBoundary } from "react-error-boundary";
 const MitreFormComponent = dynamic(
   () =>
-    import("mitre-form-component-next").then((mod) => mod.MitreFormComponent),
+    import("mitre-form-component").then((mod) => mod.MitreFormComponent),
   { ssr: false }
 );
 
@@ -198,8 +331,7 @@ const MitreFormComponent = dynamic(
       { 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!}
+    ambiente="prod"
   />
 </ErrorBoundary>;
 ```