@adatechnology/conversations-ui 0.1.0-rc.4 → 0.1.0-rc.41

package/src/preview/ConversationPreview.tsx

@@ -1,7 +1,11 @@
 /**
- * Visão lado-cliente: você digita como se fosse o cliente no WhatsApp e vê o bot responder. A
- * mensagem sai assinada para o webhook real, então o que roda aqui é o mesmo caminho de staging e
- * produção — webhook, parser, motor de conversa.
+ * Visão lado-cliente: você digita como se fosse o cliente e vê o bot responder. A mensagem sai pelo
+ * transporte real do canal — webhook assinado no WhatsApp, rota pública do widget no chat do site —,
+ * então o que roda aqui é o mesmo caminho de staging e produção: parser, motor de conversa, fluxo.
+ *
+ * O canal entra por `client` (a porta `ConversationSimulatorClient`), não por condicional aqui
+ * dentro: esta tela não sabe qual canal está simulando, e é o que permite o painel ficar no mesmo
+ * lugar da conversa para todos eles.
  *
  * É o layout de conversa de verdade (wallpaper, divisor de data, agrupamento de bolhas), não uma
  * casca de teste: o preview serve para julgar copy e fluxo, e isso só funciona se o que se vê
@@ -13,26 +17,67 @@
  */
 
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import type { MessagePayload } from '../types'
+import type { InteractiveSelection, MessagePayload } from '../types'
 import type { SSEProvider } from '../providers/types'
 import { MessageBubble } from '../MessageBubble'
 import { MessageComposer } from '../MessageComposer'
 import { DateDivider } from '../DateDivider'
 import { ConversationWallpaper } from '../Wallpaper'
 import type { PreviewWebhookClient } from './createPreviewWebhookClient'
+import {
+  acceptsMediaKind,
+  isConversationSimulatorClient,
+  mediaKindOf,
+  SIMULATOR_FILE_MEDIA_KINDS,
+  toConversationSimulatorClient,
+  type ConversationSimulatorClient,
+  type SimulatorMediaKind,
+} from './ConversationSimulatorClient'
+import { AudioRecorderButton } from '../AudioRecorderButton'
 
 export type ConversationPreviewProps = {
-  client: PreviewWebhookClient
+  /**
+   * Transporte do canal. `PreviewWebhookClient` continua aceito — é o caminho WhatsApp de antes
+   * desta porta, adaptado aqui dentro para não obrigar host nenhum a mudar de chamada.
+   */
+  client: ConversationSimulatorClient | PreviewWebhookClient
   sse: SSEProvider
   conversationId: string
   loadMessages: (conversationId: string) => Promise<MessagePayload[]>
   placeholder?: string
+  /**
+   * Recarrega o transcript a cada N ms. Serve a host SEM stream: a resposta do bot é assíncrona, e
+   * sem SSE nem polling ela só apareceria no próximo envio — o sintoma é "às vezes ele não
+   * responde". Ausente, não faz polling (host com SSE não precisa).
+   */
+  pollIntervalMs?: number
+  /**
+   * Destino alternativo do upload, no canal que sobe a mídia antes de citá-la (o caminho da Meta
+   * entrega mídia por `id`). Sem isto, usa o do próprio `client`. Canal que manda os bytes direto
+   * ignora esta prop: quem decide referência × bytes é o adaptador do canal.
+   */
+  uploadMedia?: (file: File) => Promise<PreviewUploadedMedia>
+}
+
+export type PreviewUploadedMedia = {
+  readonly mediaId: string
+  readonly mimeType?: string
+  readonly filename?: string
+}
+
+/** @deprecated Use `mediaKindOf`, que não nomeia canal. Mantido para quem já importa. */
+export function mediaTypeOf(mimeType: string): SimulatorMediaKind {
+  return mediaKindOf(mimeType)
 }
 
 // Mesma janela usada pelo WhatsApp para colar bolhas do mesmo autor: acima disso, a mensagem
 // recomeça um grupo (com rabicho e espaçamento maior).
 const GROUPING_WINDOW_MS = 5 * 60 * 1000
 
+// Escalonado, não um atraso fixo: a maioria das respostas chega em ~300ms, mas fluxo que consulta
+// catálogo ou IA demora mais — e recarregar três vezes é mais barato que a conversa parecer morta.
+const FOLLOW_UP_REFRESH_MS = [400, 1200, 3000]
+
 type RenderedMessage = {
   readonly message: MessagePayload
   readonly isFirstInGroup: boolean
@@ -55,26 +100,88 @@ function decorate(messages: readonly MessagePayload[]): RenderedMessage[] {
   })
 }
 
+/**
+ * Status HTTP do erro, quando o host o preserva.
+ *
+ * O contrato não exige um tipo de erro — cada host tem o seu —, então a leitura é estrutural: basta
+ * carregar `status` (ou `statusCode`) para ser classificável. Host que joga `new Error(texto)` cai no
+ * caminho genérico, que ainda é melhor que silêncio.
+ */
+function statusOf(error: unknown): number | undefined {
+  if (typeof error !== 'object' || error === null) return undefined
+  const candidate = error as { status?: unknown; statusCode?: unknown }
+  const value = candidate.status ?? candidate.statusCode
+  return typeof value === 'number' ? value : undefined
+}
+
+export function isNotFound(error: unknown): boolean {
+  return statusOf(error) === 404
+}
+
+export function describeLoadFailure(error: unknown): string {
+  const status = statusOf(error)
+  // 401/403 no simulador quase sempre é a aba sem sessão: `sessionStorage` é por aba, e link com
+  // `rel="noreferrer"` abre contexto novo que não herda o token do painel.
+  if (status === 401 || status === 403) {
+    return 'Sem sessão de administrador nesta aba: a mensagem é entregue no webhook, mas o transcript não pode ser lido. Entre no painel nesta mesma aba e reabra o simulador.'
+  }
+  if (error instanceof Error && error.message) return `Não foi possível ler o transcript: ${error.message}`
+  return 'Não foi possível ler o transcript da conversa.'
+}
+
 export function ConversationPreview({
   client,
   sse,
   conversationId,
   loadMessages,
   placeholder,
+  pollIntervalMs,
+  uploadMedia,
 }: ConversationPreviewProps) {
   const [messages, setMessages] = useState<MessagePayload[]>([])
   const [failure, setFailure] = useState<string | undefined>(undefined)
+  const [loadFailure, setLoadFailure] = useState<string | undefined>(undefined)
+  const [isRecording, setIsRecording] = useState(false)
+  // Mensagens que o servidor ainda não devolveu. Sem isto, quem não consegue LER a conversa (sessão
+  // ausente, API fora) digita, envia com sucesso e não vê absolutamente nada mudar — o preview fica
+  // indistinguível de quebrado. São descartadas assim que uma leitura dá certo: aí quem manda na
+  // tela é o servidor, que já tem a mensagem gravada.
+  const [pendingLocal, setPendingLocal] = useState<MessagePayload[]>([])
   const loadMessagesRef = useRef(loadMessages)
   const bottomRef = useRef<HTMLDivElement>(null)
   loadMessagesRef.current = loadMessages
 
+  const simulator = useMemo(
+    () =>
+      isConversationSimulatorClient(client)
+        ? client
+        : toConversationSimulatorClient({ client, ...(uploadMedia ? { uploadMedia } : {}) }),
+    [client, uploadMedia],
+  )
+
   const refresh = useCallback(async (): Promise<void> => {
     try {
-      setMessages(await loadMessagesRef.current(conversationId))
-    } catch {
-      // Conversa que ainda não existe é o estado normal do primeiro contato — a API responde erro
-      // e a tela deve mostrar o transcript vazio, não uma falha.
-      setMessages([])
+      const loaded = await loadMessagesRef.current(conversationId)
+      setMessages(loaded)
+      setLoadFailure(undefined)
+      // Só descarta o eco quando o servidor de fato devolveu conversa: lista vazia é "não consegui
+      // ver nada" (sessão ausente, primeiro contato), e limpar aí apagava da tela a mensagem que o
+      // usuário acabou de mandar — o sintoma que este eco existe para evitar.
+      if (loaded.length > 0) setPendingLocal([])
+    } catch (error) {
+      // Conversa que ainda não existe é o estado normal do primeiro contato — transcript vazio, sem
+      // alarme. QUALQUER outra falha precisa aparecer: engolir todas era o que transformava sessão
+      // expirada (401) em silêncio absoluto, com a thread limpa e o operador concluindo que o envio
+      // não funcionou — quando a mensagem tinha sido entregue no webhook.
+      if (isNotFound(error)) {
+        setMessages([])
+        setLoadFailure(undefined)
+        return
+      }
+
+      // Não limpa o que já está na tela: perder o histórico por causa de um refresh que falhou é
+      // dano maior que o próprio erro.
+      setLoadFailure(describeLoadFailure(error))
     }
   }, [conversationId])
 
@@ -96,18 +203,49 @@ export function ConversationPreview({
   }, [sse, conversationId, refresh])
 
   useEffect(() => {
-    bottomRef.current?.scrollIntoView({ behavior: 'smooth' })
+    if (!pollIntervalMs) return
+    const timer = setInterval(() => void refresh(), pollIntervalMs)
+    return () => clearInterval(timer)
+  }, [pollIntervalMs, refresh])
+
+  useEffect(() => {
+    // `block: 'nearest'` e não o padrão ('start'): o padrão alinha o elemento ao topo da área
+    // visível MAIS PRÓXIMA que role — e quando o container do preview não tem altura limitada, essa
+    // área é a PÁGINA. O efeito era a tela inteira saltar para baixo ao abrir/usar o simulador.
+    bottomRef.current?.scrollIntoView({ behavior: 'smooth', block: 'nearest' })
   }, [messages])
 
-  const rendered = useMemo(() => decorate(messages), [messages])
+  const rendered = useMemo(() => decorate([...messages, ...pendingLocal]), [messages, pendingLocal])
+
+  async function refreshWithFollowUps(): Promise<void> {
+    await refresh()
+    for (const atraso of FOLLOW_UP_REFRESH_MS) {
+      setTimeout(() => void refresh(), atraso)
+    }
+  }
 
   async function handleSend(text: string): Promise<void> {
     setFailure(undefined)
     try {
-      await client.sendText(text)
-      // O bot responde de forma assíncrona e o ping do SSE cobre isso; este refresh é para a
-      // própria mensagem enviada aparecer na hora, sem esperar o ciclo de evento.
-      await refresh()
+      await simulator.sendText(text)
+      setPendingLocal((current) => [
+        ...current,
+        {
+          id: `local-${current.length}-${text.length}`,
+          type: 'text',
+          content: text,
+          // Do ponto de vista do servidor, mensagem do cliente é inbound — é assim que ela aparece
+          // como "minha" nesta visão.
+          direction: 'inbound',
+          sender: 'customer',
+          timestamp: new Date().toISOString(),
+          status: 'sent',
+        },
+      ])
+      // O bot responde de forma assíncrona: gravar a resposta leva algumas centenas de ms depois do
+      // 200 do webhook. Um refresh único aqui frequentemente chegava ANTES dela, e a conversa ficava
+      // com a pergunta sem resposta até o envio seguinte.
+      await refreshWithFollowUps()
     } catch (error) {
       // A recusa mais provável é assinatura inválida (segredo divergente do que a API valida), e
       // ela precisa aparecer na tela: silenciada, o sintoma vira "mandei e não aconteceu nada".
@@ -115,6 +253,47 @@ export function ConversationPreview({
     }
   }
 
+  async function handleInteractiveSelect(selection: InteractiveSelection): Promise<void> {
+    setFailure(undefined)
+    try {
+      // A seleção viaja inteira (botão × lista) porque a forma de fio é do canal: a Meta separa
+      // `button_reply` de `list_reply` e o roteador do fluxo lê campos distintos, enquanto o chat do
+      // site manda o rótulo como texto. Decidir isso aqui faria o menu responder no simulador e
+      // falhar no aparelho do cliente.
+      await simulator.sendReply(selection)
+      await refreshWithFollowUps()
+    } catch (error) {
+      setFailure(error instanceof Error ? error.message : 'Falha ao entregar a resposta no webhook.')
+    }
+  }
+
+  /**
+   * O transporte do canal diz se aceita mídia do cliente; a tela só pergunta.
+   *
+   * Antes isto era `uploadMedia` puro, e o microfone só aparecia no produto que lembrasse de montar
+   * o upload — de onde veio a divergência entre dois simuladores da mesma casa. Agora quem responde
+   * é o adaptador: no WhatsApp ele precisa de um destino de upload, no chat do site manda os bytes.
+   */
+  const sendMedia = simulator.sendMedia
+  const canAttachFile = SIMULATOR_FILE_MEDIA_KINDS.some((kind) => acceptsMediaKind(simulator, kind))
+  const canRecordAudio = acceptsMediaKind(simulator, 'audio')
+
+  async function handleAttach(file: File): Promise<void> {
+    if (!sendMedia) return
+    setFailure(undefined)
+    try {
+      await sendMedia({
+        mediaKind: mediaKindOf(file.type),
+        file,
+        mimeType: file.type,
+        filename: file.name,
+      })
+      await refreshWithFollowUps()
+    } catch (error) {
+      setFailure(error instanceof Error ? error.message : 'Falha ao enviar o arquivo.')
+    }
+  }
+
   return (
     <div className="flex h-full min-h-0 flex-col">
       <ConversationWallpaper className="flex-1 min-h-0 overflow-y-auto px-4 py-3">
@@ -127,6 +306,11 @@ export function ConversationPreview({
               // vista do servidor.
               isMine={message.direction === 'inbound'}
               isFirstInGroup={isFirstInGroup}
+              // Só o que o bot ofereceu é tocável: reoferecer as opções da própria mensagem do
+              // cliente deixaria o menu clicável para sempre, o que o WhatsApp não faz.
+              onInteractiveSelect={
+                message.direction === 'outbound' ? (selection) => void handleInteractiveSelect(selection) : undefined
+              }
             />
           </div>
         ))}
@@ -139,9 +323,33 @@ export function ConversationPreview({
         </p>
       ) : null}
 
+      {/* Separado da falha de ENVIO: são causas diferentes e confundi-las manda o operador
+          investigar assinatura de webhook quando o problema é sessão. Amarelo, não vermelho — a
+          mensagem foi entregue; o que faltou foi poder ler a conversa de volta. */}
+      {loadFailure ? (
+        <p role="status" className="px-4 py-2 text-sm text-amber-700 dark:text-amber-400">
+          {loadFailure}
+        </p>
+      ) : null}
+
       <MessageComposer
         onSend={(text) => void handleSend(text)}
-        placeholder={placeholder ?? 'Escreva como o cliente…'}
+        onAttach={canAttachFile ? (file) => void handleAttach(file) : undefined}
+        /* Gravando, o campo diz o que falta fazer: o botão é um interruptor e o segundo toque é
+           que envia — sem esse aviso o operador grava, não vê nada acontecer e conclui que o
+           microfone está quebrado. */
+        placeholder={
+          isRecording ? 'Gravando… toque no quadrado para ouvir' : (placeholder ?? 'Escreva como o cliente…')
+        }
+        idleAction={
+          canRecordAudio ? (
+            <AudioRecorderButton
+              onRecorded={(file) => void handleAttach(file)}
+              onFailure={(message) => setFailure(message)}
+              onRecordingChange={setIsRecording}
+            />
+          ) : undefined
+        }
       />
     </div>
   )

package/src/preview/ConversationSimulatorClient.ts

@@ -0,0 +1,143 @@
+/**
+ * Copyright (c) 2026 Ada Technology. All rights reserved.
+ *
+ * This source code is proprietary and confidential. Unauthorized copying,
+ * modification, distribution, or use of this file, via any medium, is
+ * strictly prohibited without prior written permission from Ada Technology.
+ *
+ * Author: Anderson Filho <andersonfrfilho@gmail.com>
+ *
+ * Porta do simulador: o que a visão lado-cliente precisa saber fazer, sem canal no nome.
+ *
+ * O simulador nasceu falando WhatsApp — `PreviewWebhookClient`, payload assinado, mídia por
+ * `mediaId`. Só que a mesma casa atende pelo chat do próprio site, e simular ali não é uma segunda
+ * tela: é o mesmo painel, no mesmo lugar da conversa, com outro transporte. Sem esta porta cada
+ * canal novo viraria uma cópia da tela — e cópia de tela diverge, que é exatamente o que o
+ * `ConversationSimulatorPanel` existe para ter parado.
+ *
+ * O que é específico de canal fica no adaptador, nunca aqui:
+ * - **resposta de menu:** a Meta distingue `button_reply` de `list_reply`, e o roteador do fluxo lê
+ *   campos diferentes; o chat do site manda o rótulo como texto, que é literalmente o que o
+ *   visitante produz ao tocar no botão do widget. A porta entrega a seleção inteira e deixa cada
+ *   adaptador escolher a forma de fio.
+ * - **mídia:** a Meta entrega por REFERÊNCIA (sobe o arquivo primeiro, o webhook carrega o `id`); o
+ *   widget manda os BYTES no `FormData`. A porta trafega o `File` que a tela tem em mão — quem
+ *   tiver passo de upload faz o upload por dentro.
+ */
+
+import type { InteractiveSelection } from '../types'
+import type { PreviewUploadedMedia } from './createPreviewMediaUploader'
+import type { PreviewWebhookClient } from './createPreviewWebhookClient'
+
+/**
+ * Tipos de mídia que o cliente pode mandar de dentro do simulador.
+ *
+ * Subconjunto proposital do que a Meta aceita: `sticker` chega do aparelho, mas não há como
+ * escolher um no seletor de arquivo do navegador — oferecer o tipo aqui seria um caminho morto.
+ */
+export type SimulatorMediaKind = 'image' | 'video' | 'audio' | 'document'
+
+/** Os tipos que saem do seletor de arquivo. `audio` fica de fora: ele vem do microfone. */
+export const SIMULATOR_FILE_MEDIA_KINDS: readonly SimulatorMediaKind[] = ['image', 'video', 'document']
+
+/** Deriva o tipo de mídia a partir do MIME do arquivo escolhido. */
+export function mediaKindOf(mimeType: string): SimulatorMediaKind {
+  if (mimeType.startsWith('image/')) return 'image'
+  if (mimeType.startsWith('video/')) return 'video'
+  if (mimeType.startsWith('audio/')) return 'audio'
+  return 'document'
+}
+
+export type SendSimulatorMediaParams = {
+  readonly mediaKind: SimulatorMediaKind
+  /** O arquivo do disco ou o áudio recém-gravado. Referência × bytes é decisão do adaptador. */
+  readonly file: File
+  readonly mimeType?: string
+  readonly filename?: string
+  readonly caption?: string
+}
+
+export type ConversationSimulatorClient = {
+  sendText(text: string): Promise<void>
+  sendReply(selection: InteractiveSelection): Promise<void>
+  /**
+   * Ausente = este canal não recebe mídia do cliente, e o compositor não desenha clipe nem
+   * microfone. Melhor um botão que não existe do que um que falha ao ser tocado.
+   */
+  sendMedia?(params: SendSimulatorMediaParams): Promise<void>
+  /**
+   * Restringe o que `sendMedia` aceita. Ausente = todos os tipos.
+   *
+   * Existe porque canal com meia capacidade é comum: o chat do site sobe áudio (a API transcreve)
+   * mas não tem rota para imagem. Sem esta lista o clipe e o microfone apareciam juntos, e um dos
+   * dois falhava ao ser tocado.
+   */
+  readonly acceptedMediaKinds?: readonly SimulatorMediaKind[]
+}
+
+/** Responde se o compositor deve desenhar o affordance daquele tipo. */
+export function acceptsMediaKind(client: ConversationSimulatorClient, kind: SimulatorMediaKind): boolean {
+  if (!client.sendMedia) return false
+
+  return client.acceptedMediaKinds?.includes(kind) ?? true
+}
+
+export type ToSimulatorClientParams = {
+  readonly client: PreviewWebhookClient
+  /** Destino alternativo do upload. Sem isto, usa o do próprio `client`. */
+  readonly uploadMedia?: (file: File) => Promise<PreviewUploadedMedia>
+}
+
+/**
+ * Distingue a porta neutra do cliente WhatsApp legado, que continua aceito na prop.
+ *
+ * Leitura estrutural e não `instanceof`: os dois são objetos literais devolvidos por fábrica, e o
+ * host pode ter montado o seu à mão.
+ */
+export function isConversationSimulatorClient(
+  candidate: ConversationSimulatorClient | PreviewWebhookClient,
+): candidate is ConversationSimulatorClient {
+  return typeof (candidate as ConversationSimulatorClient).sendReply === 'function'
+}
+
+/**
+ * Adapta o cliente WhatsApp (webhook assinado ou ponte) para a porta neutra.
+ *
+ * O upload vive aqui dentro porque ele é uma etapa DO CANAL: no caminho da Meta a mídia precisa
+ * existir como `id` antes do webhook citá-la. Sem passo de upload disponível, `sendMedia` sai
+ * ausente — é o que mantém o clipe escondido em host que não montou destino para o arquivo, o
+ * comportamento que já existia antes desta porta.
+ */
+export function toConversationSimulatorClient({
+  client,
+  uploadMedia,
+}: ToSimulatorClientParams): ConversationSimulatorClient {
+  const upload = uploadMedia ?? client.uploadMedia
+
+  const base: ConversationSimulatorClient = {
+    sendText: (text) => client.sendText(text),
+    sendReply: (selection) => {
+      const reply = { id: selection.option.id, title: selection.option.title }
+      return selection.kind === 'button' ? client.sendButtonReply(reply) : client.sendListReply(reply)
+    },
+  }
+
+  if (!upload) return base
+
+  return {
+    ...base,
+    sendMedia: async ({ mediaKind, file, mimeType, filename, caption }) => {
+      const uploaded = await upload(file)
+      await client.sendMedia({
+        // O tipo sai do MIME que o upload devolveu quando ele existe: host que normaliza o formato
+        // (áudio gravado em `webm` que sobe como `ogg`) mudava de tipo, e a mídia chegava como
+        // documento.
+        mediaType: uploaded.mimeType ? mediaKindOf(uploaded.mimeType) : mediaKind,
+        mediaId: uploaded.mediaId,
+        mimeType: uploaded.mimeType ?? mimeType ?? file.type,
+        filename: uploaded.filename ?? filename ?? file.name,
+        ...(caption ? { caption } : {}),
+      })
+    },
+  }
+}

package/src/preview/ConversationSimulatorPanel.test.tsx

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { ConversationSimulatorPanel, type ConversationSimulatorPanelProps } from './ConversationSimulatorPanel'
+import { createMockSSEProvider } from './createMockSSEProvider'
+import { createPreviewStore } from './previewStore'
+
+function markupOf(overrides: Partial<ConversationSimulatorPanelProps> = {}): string {
+  const store = createPreviewStore({ conversations: [], messages: {} })
+
+  return renderToStaticMarkup(
+    <ConversationSimulatorPanel
+      conversationId="5511900000042"
+      onClose={() => {}}
+      client={{ sendText: async () => {}, sendInteractiveReply: async () => {} } as never}
+      sse={createMockSSEProvider({ store })}
+      loadMessages={async () => []}
+      {...overrides}
+    />,
+  )
+}
+
+describe('ConversationSimulatorPanel', () => {
+  it('mostra o telefone formatado pelo host, e não o id cru', () => {
+    expect(markupOf({ displayNumber: '+55 (11) 90000-0042' })).toContain('+55 (11) 90000-0042')
+  })
+
+  it('cai no id da conversa quando o host não formata', () => {
+    expect(markupOf()).toContain('5511900000042')
+  })
+
+  it('avisa para onde a mensagem vai, para ninguém achar que é conversa de mentira', () => {
+    expect(markupOf()).toContain('entrega no webhook real')
+  })
+
+  it('dá nome acessível ao botão de fechar, que só tem ícone', () => {
+    expect(markupOf()).toContain('aria-label="Fechar simulador"')
+  })
+
+  it('aceita rótulos parciais do host sem exigir o conjunto inteiro', () => {
+    const markup = markupOf({ labels: { title: 'Testar fluxo' } })
+
+    expect(markup).toContain('Testar fluxo')
+    // O que não foi sobrescrito continua no default.
+    expect(markup).toContain('aria-label="Fechar simulador"')
+  })
+
+  it('renderiza ação extra do host no cabeçalho', () => {
+    expect(markupOf({ headerActions: <button type="button">Rodar roteiro</button> })).toContain('Rodar roteiro')
+  })
+
+  it('nomeia o próprio aside, para o leitor de tela distinguir do transcript ao lado', () => {
+    expect(markupOf()).toContain('aria-label="Simulador do cliente"')
+  })
+})

package/src/preview/ConversationSimulatorPanel.tsx

@@ -0,0 +1,131 @@
+/**
+ * Copyright (c) 2026 Ada Technology. All rights reserved.
+ *
+ * This source code is proprietary and confidential. Unauthorized copying,
+ * modification, distribution, or use of this file, via any medium, is
+ * strictly prohibited without prior written permission from Ada Technology.
+ *
+ * Author: Anderson Filho <andersonfrfilho@gmail.com>
+ *
+ * Painel lateral do simulador de cliente: a moldura em volta do `ConversationPreview`.
+ *
+ * Existe como componente do pacote porque cada produto tinha reescrito a mesma moldura —
+ * `<aside>`, cabeçalho com título e telefone, botão de fechar — e as cópias divergiram. Uma delas
+ * migrou para o cliente-ponte (assinatura no servidor) e a outra ficou assinando no navegador, com
+ * o app secret publicado no bundle. É o tipo de correção que precisa chegar a todo mundo de uma vez.
+ *
+ * Mora DENTRO da tela de conversas, e não numa aba própria, por um motivo prático: o token do
+ * atendente costuma viver em `sessionStorage`, que é por aba. Numa aba separada o simulador nascia
+ * sem sessão, o transcript nunca carregava, e o sintoma era "mandei e não aconteceu nada".
+ *
+ * O efeito de cada envio aparece na thread ao lado pelo mesmo stream que a inbox já assina — este
+ * painel não abre conexão própria.
+ *
+ * A moldura é a mesma em todo canal — o que muda é o transporte, que entra pelo `client`, e duas
+ * frases do cabeçalho: dizer "entrega no webhook real" num chat de site descreveria um caminho que
+ * ali não existe, e "escreva como o cliente" num visitante anônimo nomeia alguém que ainda não é.
+ */
+
+import type { ReactNode } from 'react'
+
+import { CONVERSATION_CHANNEL, DEFAULT_CONVERSATION_CHANNEL, type ConversationChannel } from '../conversationChannel'
+import { ConversationPreview, type ConversationPreviewProps } from './ConversationPreview'
+
+export type ConversationSimulatorPanelLabels = {
+  readonly title: string
+  /** Complementa o identificador no subtítulo, explicando para onde a mensagem realmente vai. */
+  readonly destinationHint: string
+  readonly close: string
+  readonly placeholder: string
+}
+
+export const DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS: ConversationSimulatorPanelLabels = {
+  title: 'Simulador do cliente',
+  destinationHint: 'entrega no webhook real',
+  close: 'Fechar simulador',
+  placeholder: 'Escreva como o cliente…',
+}
+
+type ChannelWording = Pick<ConversationSimulatorPanelLabels, 'destinationHint' | 'placeholder'>
+
+/** Só o que muda de canal para canal; o resto continua vindo do default. */
+const SIMULATOR_PANEL_CHANNEL_WORDING: Readonly<Record<ConversationChannel, ChannelWording>> = {
+  [CONVERSATION_CHANNEL.WHATSAPP]: {
+    destinationHint: DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS.destinationHint,
+    placeholder: DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS.placeholder,
+  },
+  [CONVERSATION_CHANNEL.MESSENGER]: {
+    destinationHint: DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS.destinationHint,
+    placeholder: DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS.placeholder,
+  },
+  [CONVERSATION_CHANNEL.INSTAGRAM]: {
+    destinationHint: DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS.destinationHint,
+    placeholder: DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS.placeholder,
+  },
+  [CONVERSATION_CHANNEL.WEBCHAT]: {
+    destinationHint: 'entrega na API do chat do site',
+    placeholder: 'Escreva como o visitante…',
+  },
+}
+
+/** Rótulos do painel já resolvidos para o canal — útil para o host que monta o cabeçalho por fora. */
+export function simulatorPanelLabelsOf(channel: ConversationChannel | undefined): ConversationSimulatorPanelLabels {
+  return {
+    ...DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS,
+    ...SIMULATOR_PANEL_CHANNEL_WORDING[channel ?? DEFAULT_CONVERSATION_CHANNEL],
+  }
+}
+
+export type ConversationSimulatorPanelProps = Omit<ConversationPreviewProps, 'placeholder'> & {
+  readonly onClose: () => void
+  /** Ausente = WhatsApp, que era o único canal antes desta prop existir. */
+  readonly channel?: ConversationChannel
+  /**
+   * Identificador do contato já formatado para leitura — telefone no WhatsApp, apelido no Instagram,
+   * "Visitante 3f9c21" no chat do site. É o host que formata: máscara de telefone é convenção
+   * regional, e o pacote não tem como saber a do produto.
+   */
+  readonly displayHandle?: string
+  /** @deprecated Use `displayHandle` — o simulador deixou de ser só telefone. */
+  readonly displayNumber?: string
+  readonly labels?: Partial<ConversationSimulatorPanelLabels>
+  /** Ações extras no cabeçalho — roteiro automático, limpar conversa, trocar de contato. */
+  readonly headerActions?: ReactNode
+}
+
+export function ConversationSimulatorPanel({
+  onClose,
+  channel,
+  displayHandle,
+  displayNumber,
+  labels,
+  headerActions,
+  ...previewProps
+}: ConversationSimulatorPanelProps) {
+  const text = { ...simulatorPanelLabelsOf(channel), ...labels }
+  const subtitle = [displayHandle ?? displayNumber ?? previewProps.conversationId, text.destinationHint].join(' · ')
+
+  return (
+    <aside className="cv-simulator-panel" aria-label={text.title}>
+      <header className="cv-simulator-panel__header">
+        <div className="cv-simulator-panel__heading">
+          <h2 className="cv-simulator-panel__title">{text.title}</h2>
+          <p className="cv-simulator-panel__subtitle">{subtitle}</p>
+        </div>
+        <div className="cv-simulator-panel__actions">
+          {headerActions}
+          <button type="button" onClick={onClose} data-cv-tooltip={text.close} aria-label={text.close} className="cv-simulator-panel__close">
+            {/* SVG inline em vez de lucide-react: o pacote não impõe biblioteca de ícone ao host. */}
+            <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden="true">
+              <path d="M18 6 6 18M6 6l12 12" />
+            </svg>
+          </button>
+        </div>
+      </header>
+
+      <div className="cv-simulator-panel__body">
+        <ConversationPreview {...previewProps} placeholder={text.placeholder} />
+      </div>
+    </aside>
+  )
+}