Mitre Actions Widget

Componente flutuante com botões de ações rápidas para ser usado em projetos da Mitre Realty. Esta biblioteca oferece um botão fixo que permite o acesso rápido a canais de contato como WhatsApp e ligação telefônica.

🚨 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

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

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

import { MitreActionsWidget } from "mitre-actions-widget";

// 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"}]'

<MitreActionsWidget
  products={products}
  environment="prod"
/>

// Com cor personalizada
<MitreActionsWidget
  products={products}
  environment="prod"
  backgroundColor="#FF5733"
/>

// Com barra fixa inferior no desktop (opt-in)
<MitreActionsWidget
  products={products}
  environment="prod"
  bottomBar
  backgroundColor="#1E1E1E" // fundo da barra
  textColor="#FFFFFF"       // texto/ícones da barra
  phoneNumber="+551148100600"
/>

// Com customização do formulário e callback de sucesso (props opcionais)
<MitreActionsWidget
  products={products}
  environment="prod"
  // formShowHeader={true}
  // formTitle="Fale conosco"
  // formSubtitle="Preencha o formulário abaixo"
  // formShowContactPreference={true}
  // onFormSuccess={(body, leadId) => console.log("Lead criado:", leadId)}
/>

🛠️ Tecnologias utilizadas

• React
• Styled Components
• React Icons
• Vite
• Tsup

✨ Características

Estilos Isolados

A partir da versão 1.0.0, todos os estilos do componente são completamente encapsulados e não afetam outros elementos da aplicação. Isso significa:

• ✅ Sem conflitos de CSS: As variáveis e estilos do componente não interferem com o projeto host
• ✅ Sem dependências globais: Não é necessário adicionar fontes ou resets CSS no projeto
• ✅ Fonte integrada: A fonte Montserrat é carregada automaticamente pelo componente (verificando se já existe para evitar duplicação)
• ✅ Reset CSS scoped: Regras de reset aplicadas apenas ao escopo do componente

O componente gerencia internamente:

• Fonte Google (Montserrat) com fallbacks para fontes do sistema
• Paleta de cores própria
• Reset CSS localizado
• Customização de scrollbar apenas nos elementos internos

Importante: Esta é uma mudança que melhora significativamente a integração do componente em projetos externos, eliminando side effects indesejados.

⚙️ 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-actions-widget

# Usando yarn
yarn add mitre-actions-widget

# Usando pnpm
pnpm add mitre-actions-widget

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

🔧 Props do Componente

O MitreActionsWidget aceita as seguintes props:

• products (Product[]): Array de produtos do empreendimento.
• environment ("staging" | "prod", opcional): Define de qual config interno do mitre-form-component o widget lê apiUrl, apiToken, whatsappPhone e chatUrl. Padrão: "staging".
• backgroundColor (string, opcional): Cor de fundo personalizada para o botão flutuante e para a barra inferior (quando ativa). Padrão: #000000 (preto).
• bottomBar (boolean, opcional): Ativa a barra fixa inferior em desktop/telas médias (largura ≥ 1024px). O botão flutuante permanece sempre visível (mobile e desktop); no desktop ele flutua logo acima da barra. Em telas menores a barra some e apenas o botão flutuante aparece. Padrão: false.
• textColor (string, opcional): Cor do texto e dos ícones da barra inferior. Padrão: #FFF (branco).
• phoneNumber (string, opcional): Número de telefone para contato via ligação (vira um link tel:). Habilita o atalho "Ligue para nós" na barra inferior e a opção "Atendimento por ligação" dentro de "Converse com um corretor". Se ausente, os itens de ligação não são exibidos. Ex.: phoneNumber="+551148100600".
• formShowHeader (boolean, opcional): Exibe ou oculta o cabeçalho do formulário.
• formTitle (string, opcional): Título exibido no cabeçalho do formulário.
• formSubtitle (string, opcional): Subtítulo exibido no cabeçalho do formulário.
• formShowContactPreference (boolean, opcional): Exibe ou oculta o campo de preferência de contato no formulário.
• onFormSuccess ((requestBody, leadId) => void, opcional): Callback chamado após o envio bem-sucedido do formulário. Recebe o corpo da requisição (RequestBody) e o ID do lead gerado.

🚨 Componente dentro de um ErrorBoundary

Recomendamos que o componente MitreActionsWidget 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 MitreActionsWidget = dynamic(
  () => import("mitre-actions-widget").then((mod) => mod.MitreActionsWidget),
  { ssr: false }
);

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

<ErrorBoundary fallback={<div>Erro ao carregar o formulário</div>}>
  <MitreActionsWidget
    products={products}
    environment="prod"
    backgroundColor="#2DCE68" // Opcional: cor personalizada
    // formShowHeader={true}
    // formTitle="Fale conosco"
    // formSubtitle="Preencha o formulário abaixo"
    // formShowContactPreference={true}
    // onFormSuccess={(body, leadId) => console.log("Lead criado:", leadId)}
  />
</ErrorBoundary>;

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

🏗️ Como gerar o build e publicar no npm

O processo completo de release (login no npm, versionamento por SemVer, build, --dry-run, publish com OTP e verificação) está documentado em docs/publicar-no-npm.md.

Resumo:

npm version patch --no-git-tag-version   # ou minor / major
yarn build                               # regenera dist/ (não versionado)
npm publish --dry-run                    # confere o conteúdo do pacote
npm publish                              # com 2FA: --otp=<código>
git commit -am "chore: release vX.Y.Z" && git push

📄 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.