@adatechnology/conversations-ui 0.1.0-rc.9 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adatechnology/conversations-ui",
-  "version": "0.1.0-rc.9",
+  "version": "0.1.0",
   "description": "WhatsApp conversation UI components — parametrizável por endpoint, tema e feature flags",
   "publishConfig": {
     "access": "public"
@@ -31,12 +31,12 @@
     "clsx": "^2.1.1",
     "lucide-react": "^1.21.0",
     "tailwind-merge": "^3.6.0",
-    "@adatechnology/meta-whatsapp-contracts": "0.2.0-rc.6"
+    "@adatechnology/meta-whatsapp-contracts": "0.2.0"
   },
   "peerDependencies": {
+    "@xyflow/react": "^12",
     "react": "^18 || ^19",
-    "react-dom": "^18 || ^19",
-    "@xyflow/react": "^12"
+    "react-dom": "^18 || ^19"
   },
   "peerDependenciesMeta": {
     "@xyflow/react": {
@@ -45,13 +45,14 @@
   },
   "devDependencies": {
     "@types/bun": "1.3.14",
-    "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
     "@types/react": "^18 || ^19",
-    "@types/react-dom": "^18 || ^19"
+    "@types/react-dom": "^18 || ^19",
+    "@xyflow/react": "^12",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/flows/index.ts src/channel/index.ts src/preview/index.ts src/styles.css --dts --format esm --external react --external react-dom --external @xyflow/react",
+    "build": "tsup src/index.ts src/flows/index.ts src/channel/index.ts src/preview/index.ts src/styles.css --dts --clean --format esm --external react --external react-dom --external @xyflow/react",
     "build:watch": "tsup src/index.ts src/flows/index.ts src/channel/index.ts src/styles.css --watch --dts --format esm --external react --external react-dom --external @xyflow/react",
     "check": "tsc -p tsconfig.json --noEmit",
     "test": "bun test"

package/src/AudioPlayer.tsx

@@ -15,6 +15,13 @@ const BARS = Array.from({ length: 30 }, (_, i) => {
   return heights[i % heights.length]
 })
 
+// O player não recebe bag de rótulos do host: são duas palavras, e criar um contrato de labels só
+// para elas custaria mais do que resolve.
+const AUDIO_PLAYER_LABELS = {
+  play: 'Reproduzir',
+  pause: 'Pausar',
+} as const
+
 function fmt(sec: number): string {
   if (!isFinite(sec)) return '0:00'
   const m = Math.floor(sec / 60)
@@ -77,6 +84,7 @@ export function AudioPlayer({ src, isMine = false }: AudioPlayerProps) {
       <audio ref={audioRef} src={src} preload="metadata" />
 
       <button
+        data-cv-tooltip={playing ? AUDIO_PLAYER_LABELS.pause : AUDIO_PLAYER_LABELS.play} aria-label={playing ? AUDIO_PLAYER_LABELS.pause : AUDIO_PLAYER_LABELS.play}
         onClick={toggle}
         className={`flex-shrink-0 w-9 h-9 rounded-full flex items-center justify-center transition-colors ${playBtn}`}
       >

package/src/AudioRecorderButton.test.tsx

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { AudioRecorderButton, DEFAULT_AUDIO_RECORDER_BUTTON_LABELS } from './AudioRecorderButton'
+
+const noop = () => {}
+
+describe('AudioRecorderButton', () => {
+  it('começa oferecendo gravar, sem painel de revisão à vista', () => {
+    const markup = renderToStaticMarkup(<AudioRecorderButton onRecorded={noop} />)
+
+    expect(markup).toContain(`data-cv-tooltip="${DEFAULT_AUDIO_RECORDER_BUTTON_LABELS.start}"`)
+    expect(markup).not.toContain(`data-cv-tooltip="${DEFAULT_AUDIO_RECORDER_BUTTON_LABELS.send}"`)
+    expect(markup).not.toContain('<audio')
+  })
+
+  it('deixa o host trocar o texto de um rótulo sem perder os outros', () => {
+    const markup = renderToStaticMarkup(
+      <AudioRecorderButton onRecorded={noop} labels={{ start: 'Gravar recado' }} />,
+    )
+
+    expect(markup).toContain('data-cv-tooltip="Gravar recado"')
+  })
+
+  it('mantém a caixa de 40px do botão de enviar para a barra não pular', () => {
+    const markup = renderToStaticMarkup(<AudioRecorderButton onRecorded={noop} />)
+
+    expect(markup).toContain('h-10 w-10')
+  })
+})

package/src/AudioRecorderButton.tsx

@@ -0,0 +1,248 @@
+/**
+ * Gravação de áudio no simulador, pelo microfone do próprio navegador.
+ *
+ * Existe porque áudio é o formato que mais chega de cliente real e o que mais quebra fluxo: sem
+ * poder gravar aqui, testar o caminho de transcrição exigia mandar mensagem do celular de alguém.
+ *
+ * O arquivo gravado sai daqui como `File` e segue exatamente o mesmo caminho de um anexo — quem
+ * hospeda e devolve o `mediaId` é o host, via `uploadMedia`.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { AudioPlayer } from './AudioPlayer'
+
+export interface AudioRecorderButtonLabels {
+  start: string
+  stop: string
+  unsupported: string
+  denied: string
+  review: string
+  send: string
+  discard: string
+  empty: string
+}
+
+export const DEFAULT_AUDIO_RECORDER_BUTTON_LABELS: AudioRecorderButtonLabels = {
+  start: 'Gravar áudio',
+  stop: 'Parar gravação',
+  unsupported: 'Este navegador não grava áudio.',
+  denied: 'Sem permissão para usar o microfone.',
+  review: 'Ouça antes de enviar',
+  send: 'Enviar áudio',
+  discard: 'Descartar áudio',
+  empty: 'Nada foi captado pelo microfone.',
+}
+
+export interface AudioRecorderButtonProps {
+  onRecorded: (file: File) => void | Promise<void>
+  onFailure?: (message: string) => void
+  /**
+   * Avisa quando a gravação começa e termina. O botão é um interruptor — o segundo toque é que
+   * envia — e sem um aviso fora dele o operador grava, não vê nada acontecer e desiste achando
+   * que o microfone está quebrado.
+   */
+  onRecordingChange?: (isRecording: boolean) => void
+  /**
+   * Abre uma etapa de revisão quando a gravação para: o áudio toca ali mesmo e só sai depois de
+   * confirmado. Ligado por padrão — voz é o único anexo que quem envia não viu antes de mandar, e
+   * sem ouvir não há como saber se o microfone captou alguma coisa. Desligar volta ao envio direto.
+   */
+  reviewBeforeSend?: boolean
+  /**
+   * Teto de duração da gravação, em milissegundos. Passado o tempo, o gravador para e envia o que
+   * tem. Produto com limite próprio sobrescreve.
+   */
+  maxDurationMilliseconds?: number
+  labels?: Partial<AudioRecorderButtonLabels>
+  disabled?: boolean
+}
+
+/**
+ * Cinco minutos: com o codec de voz do WhatsApp isso dá menos de 3MB, folgado dentro do teto de
+ * 16MB que a Meta impõe a áudio, e é mais do que qualquer recado de cliente. O corte automático
+ * existe porque gravação esquecida aberta só se descobre no envio, com o arquivo inteiro perdido.
+ */
+export const DEFAULT_MAX_RECORDING_MILLISECONDS = 5 * 60 * 1000
+
+/**
+ * Ordem de preferência de formato: os dois primeiros o WhatsApp aceita como áudio; `webm` é só
+ * saída de emergência para navegador que não grava mais nada — gravar em webm e descobrir na hora
+ * do envio que o formato é inválido é pior do que gravar já no formato certo.
+ */
+const RECORDING_FORMATS = [
+  { mimeType: 'audio/ogg;codecs=opus', uploadMimeType: 'audio/ogg', extension: 'ogg' },
+  { mimeType: 'audio/mp4', uploadMimeType: 'audio/mp4', extension: 'm4a' },
+  { mimeType: 'audio/webm', uploadMimeType: 'audio/webm', extension: 'webm' },
+] as const
+
+export type RecordingFormat = (typeof RECORDING_FORMATS)[number]
+
+/** Primeiro formato que o navegador sabe gravar, ou `undefined` se não souber gravar nenhum. */
+export function resolveRecordingFormat(): RecordingFormat | undefined {
+  if (typeof MediaRecorder === 'undefined') return undefined
+  // `isTypeSupported` não existe em toda implementação; onde falta, o primeiro da lista é o palpite.
+  if (typeof MediaRecorder.isTypeSupported !== 'function') return RECORDING_FORMATS[0]
+  return RECORDING_FORMATS.find((format) => MediaRecorder.isTypeSupported(format.mimeType))
+}
+
+type PendingRecording = { file: File; objectURL: string }
+
+export function AudioRecorderButton({
+  onRecorded,
+  onFailure,
+  onRecordingChange,
+  reviewBeforeSend = true,
+  maxDurationMilliseconds = DEFAULT_MAX_RECORDING_MILLISECONDS,
+  labels,
+  disabled,
+}: AudioRecorderButtonProps) {
+  const labelOf = (key: keyof AudioRecorderButtonLabels): string =>
+    labels?.[key] ?? DEFAULT_AUDIO_RECORDER_BUTTON_LABELS[key]
+  const [isRecording, setIsRecording] = useState(false)
+  const [pending, setPending] = useState<PendingRecording | undefined>(undefined)
+  const recorderRef = useRef<MediaRecorder | null>(null)
+  const autoStopRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+
+  // O `objectURL` é um recurso do documento, não do React: sem revogar, cada gravação descartada
+  // deixa o blob inteiro preso na memória da aba até um reload.
+  const discard = useCallback(() => {
+    setPending((current) => {
+      if (current) URL.revokeObjectURL(current.objectURL)
+      return undefined
+    })
+  }, [])
+
+  useEffect(() => discard, [discard])
+
+  const confirm = useCallback(() => {
+    if (!pending) return
+    void onRecorded(pending.file)
+    discard()
+  }, [discard, onRecorded, pending])
+
+  const stop = useCallback(() => {
+    recorderRef.current?.stop()
+  }, [])
+
+  const start = useCallback(async () => {
+    const format = resolveRecordingFormat()
+    if (!format || !navigator.mediaDevices?.getUserMedia) {
+      onFailure?.(labels?.unsupported ?? DEFAULT_AUDIO_RECORDER_BUTTON_LABELS.unsupported)
+      return
+    }
+
+    try {
+      const stream = await navigator.mediaDevices.getUserMedia({ audio: true })
+      const recorder = new MediaRecorder(stream, { mimeType: format.mimeType })
+      const chunks: Blob[] = []
+
+      recorder.addEventListener('dataavailable', (event) => {
+        if (event.data.size > 0) chunks.push(event.data)
+      })
+      recorder.addEventListener('stop', () => {
+        // Solta o microfone assim que para: sem isto o indicador de gravação do navegador fica
+        // aceso depois do envio, e o operador acha que o simulador continua ouvindo.
+        stream.getTracks().forEach((track) => track.stop())
+        clearTimeout(autoStopRef.current)
+        setIsRecording(false)
+        onRecordingChange?.(false)
+        recorderRef.current = null
+        // O `File` sai com o MIME sem os parâmetros de codec: `audio/ogg;codecs=opus` serve ao
+        // gravador, mas quem valida upload compara com `audio/ogg` puro.
+        const blob = new Blob(chunks, { type: format.uploadMimeType })
+        const file = new File([blob], `audio-${Date.now()}.${format.extension}`, {
+          type: format.uploadMimeType,
+        })
+
+        // Gravação vazia não vira anexo: microfone mudo ou permissão revogada no meio produzem um
+        // blob de zero byte, e mandá-lo adiante só falha lá na frente, sem dizer por quê.
+        if (blob.size === 0) {
+          onFailure?.(labelOf('empty'))
+          return
+        }
+
+        if (!reviewBeforeSend) {
+          void onRecorded(file)
+          return
+        }
+
+        setPending({ file, objectURL: URL.createObjectURL(blob) })
+      })
+
+      recorderRef.current = recorder
+      recorder.start()
+      autoStopRef.current = setTimeout(() => recorder.stop(), maxDurationMilliseconds)
+      setIsRecording(true)
+      onRecordingChange?.(true)
+    } catch {
+      onFailure?.(labels?.denied ?? DEFAULT_AUDIO_RECORDER_BUTTON_LABELS.denied)
+    }
+    // `labelOf` lê `labels` a cada render e não entra aqui; o que importa para recriar o gravador
+    // são o teto de duração, o destino da gravação e se há etapa de revisão.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [maxDurationMilliseconds, onFailure, onRecorded, onRecordingChange, reviewBeforeSend])
+
+  const toggleLabel = isRecording ? labelOf('stop') : labelOf('start')
+
+  return (
+    /* O painel de revisão flutua sobre o botão em vez de ocupar espaço na barra: o microfone mora
+       na caixa do botão de enviar, e empurrar o composer para cima a cada gravação faria a
+       conversa saltar. */
+    <div className="relative flex-shrink-0">
+      {pending && (
+        <div
+          role="group"
+          aria-label={labelOf('review')}
+          /* Largura presa à viewport, não ao conteúdo: ancorado à direita do microfone, qualquer
+             largura fixa maior que a tela sangra para fora no celular. `flex-wrap` é a segunda
+             rede — se o player e os dois botões não couberem lado a lado, os botões descem. */
+          className="absolute bottom-full right-0 z-20 mb-2 flex w-[calc(100vw-2rem)] max-w-[20rem] flex-wrap items-center justify-end gap-2 rounded-xl border border-gray-200 bg-white p-2 shadow-lg dark:border-gray-700 dark:bg-gray-800"
+        >
+          <div className="min-w-0 flex-1">
+            <AudioPlayer src={pending.objectURL} />
+          </div>
+          <button
+            type="button"
+            onClick={discard}
+            data-cv-tooltip={labelOf('discard')}
+            aria-label={labelOf('discard')}
+            className="flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-full text-gray-500 transition-colors hover:bg-gray-100 hover:text-red-500 dark:hover:bg-gray-700"
+          >
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round"><line x1="18" y1="6" x2="6" y2="18" /><line x1="6" y1="6" x2="18" y2="18" /></svg>
+          </button>
+          <button
+            type="button"
+            onClick={confirm}
+            data-cv-tooltip={labelOf('send')}
+            aria-label={labelOf('send')}
+            className="flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-full bg-emerald-500 text-white transition-colors hover:bg-emerald-600"
+          >
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor"><path d="M2.01 21L23 12 2.01 3 2 10l15 2-15 2z" /></svg>
+          </button>
+        </div>
+      )}
+      <button
+        type="button"
+        disabled={disabled || pending !== undefined}
+        onClick={() => (isRecording ? stop() : void start())}
+        data-cv-tooltip={toggleLabel}
+        aria-label={toggleLabel}
+        aria-pressed={isRecording}
+        /* Mesma caixa do botão de enviar: o microfone ocupa o lugar dele enquanto o campo está
+           vazio, e qualquer diferença de tamanho faz a barra pular a cada letra digitada. */
+        className={`flex h-10 w-10 items-center justify-center rounded-full transition-colors disabled:opacity-50 ${
+          isRecording
+            ? 'animate-pulse bg-red-500 text-white ring-4 ring-red-500/30 hover:bg-red-600'
+            : 'text-gray-500 hover:bg-gray-200 dark:hover:bg-gray-700'
+        }`}
+      >
+        {isRecording ? (
+          <svg width="18" height="18" viewBox="0 0 24 24" fill="currentColor"><rect x="6" y="6" width="12" height="12" rx="2" /></svg>
+        ) : (
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round"><path d="M12 2a3 3 0 0 0-3 3v7a3 3 0 0 0 6 0V5a3 3 0 0 0-3-3z" /><path d="M19 11a7 7 0 0 1-14 0" /><line x1="12" y1="18" x2="12" y2="22" /></svg>
+        )}
+      </button>
+    </div>
+  )
+}

package/src/AudioTranscription.test.tsx

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { AudioTranscription } from './AudioTranscription'
+import type { MessageTranscription } from './types'
+
+function render(props: {
+  transcription?: MessageTranscription | null
+  onTranscribe?: () => Promise<void>
+}): string {
+  return renderToStaticMarkup(<AudioTranscription {...props} />)
+}
+
+const noop = async () => undefined
+
+describe('AudioTranscription', () => {
+  it('mostra o texto e oferece copiar', () => {
+    const markup = render({ transcription: { status: 'done', text: 'quero dois pães na chapa' } })
+
+    expect(markup).toContain('quero dois pães na chapa')
+    expect(markup).toContain('Copiar')
+  })
+
+  it('deixa o texto selecionável — é o caminho de quem não tem clipboard disponível', () => {
+    const markup = render({ transcription: { status: 'done', text: 'oi' } })
+
+    expect(markup).toContain('select-all')
+  })
+
+  it('não oferece copiar quando não há texto para copiar', () => {
+    const markup = render({ transcription: { status: 'done', text: '' } })
+
+    expect(markup).not.toContain('Copiar')
+  })
+
+  // Silêncio processado é diferente de não transcrito: sem essa distinção o operador clica em
+  // transcrever de novo atrás de um texto que não existe.
+  it('diz "sem fala detectada" em áudio processado e vazio, sem oferecer transcrever', () => {
+    const markup = render({ transcription: { status: 'done', text: '   ' } })
+
+    expect(markup).toContain('Sem fala detectada')
+    expect(markup).not.toContain('Transcrever áudio')
+  })
+
+  it('oferece transcrever quando nada foi avaliado ainda', () => {
+    const markup = render({ transcription: null, onTranscribe: noop })
+
+    expect(markup).toContain('Transcrever áudio')
+  })
+
+  // Mesmo padrão de takeover/release: sem a porta, a afordância não existe — melhor que um botão
+  // que estoura no clique.
+  it('não desenha nada quando não há transcrição nem forma de pedir uma', () => {
+    expect(render({ transcription: null })).toBe('')
+    expect(render({})).toBe('')
+  })
+
+  it('mostra falha com convite a tentar de novo', () => {
+    const markup = render({ transcription: { status: 'failed' }, onTranscribe: noop })
+
+    expect(markup).toContain('Falha ao transcrever')
+  })
+
+  it('trata pendente como em andamento — já foi tentado e vai sair', () => {
+    const markup = render({ transcription: { status: 'pending' }, onTranscribe: noop })
+
+    expect(markup).toContain('Transcrevendo...')
+  })
+
+  it('avisa formato não suportado sem oferecer retry — retentar não conserta codec', () => {
+    const markup = render({ transcription: { status: 'unsupported' }, onTranscribe: noop })
+
+    expect(markup).toContain('não suportado')
+    expect(markup).not.toContain('Transcrever novamente')
+  })
+
+  /**
+   * Medido: 1147 caracteres produziram uma bolha de 854px, mais alta que a área visível da conversa.
+   * Sem o recolhimento, uma nota de voz longa esconde as mensagens seguintes.
+   */
+  it('recolhe transcrição longa e oferece ver o texto completo', () => {
+    const markup = render({ transcription: { status: 'done', text: 'palavra '.repeat(60).trim() } })
+
+    expect(markup).toContain('ver transcrição completa')
+    expect(markup).toContain('-webkit-line-clamp')
+  })
+
+  it('não recolhe transcrição curta', () => {
+    const markup = render({ transcription: { status: 'done', text: 'quero dois pães' } })
+
+    expect(markup).not.toContain('ver transcrição completa')
+    expect(markup).not.toContain('-webkit-line-clamp')
+  })
+
+  // Recolher é sobre altura na tela; o operador cola o pedido inteiro no sistema interno.
+  it('mantém o texto inteiro no DOM mesmo recolhido, para o copiar levar tudo', () => {
+    const markup = render({ transcription: { status: 'done', text: 'primeira ' + 'meio '.repeat(70) + 'ultima' } })
+
+    expect(markup).toContain('primeira')
+    expect(markup).toContain('ultima')
+  })
+
+  it('oferece retranscrever quando já há texto e o host sabe transcrever', () => {
+    const markup = render({ transcription: { status: 'done', text: 'ruim' }, onTranscribe: noop })
+
+    expect(markup).toContain('Transcrever novamente')
+  })
+
+  it('não oferece retranscrever quando o host não sabe transcrever', () => {
+    const markup = render({ transcription: { status: 'done', text: 'ok' } })
+
+    expect(markup).toContain('ok')
+    expect(markup).not.toContain('Transcrever novamente')
+  })
+})