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

package/src/DocumentsLibrary.tsx

@@ -0,0 +1,322 @@
+/**
+ * Biblioteca de arquivos de TODAS as conversas — a tela de Documentos do painel, fora do
+ * atendimento.
+ *
+ * Distinta do `ConversationDocumentsPanel`: aquele parte de uma conversa aberta e vive dentro dela;
+ * esta varre a empresa e por isso mostra de qual conversa cada arquivo veio, com o número
+ * clicável. Sem essa referência, uma lista global de anexos não responde nenhuma pergunta.
+ */
+
+import { useEffect, useState } from 'react'
+import { ArrowUpDown, Bot, Download, Eye, MessageSquare, Users } from 'lucide-react'
+import { useConversations } from './providers/ConversationsProvider'
+import { DOCUMENT_SOURCE_FILTER, type DocumentSourceFilter } from './ConversationDocumentsPanel'
+import { FileIcon } from './FileIcon'
+import { cn } from './lib/cn'
+import { formatDateTime, formatFileSize } from './lib/format'
+import { formatPhone } from './lib/phone'
+import type { CompanyDocument } from './providers/types'
+
+export interface DocumentsLibraryLabels {
+  title: string
+  searchPlaceholder: string
+  empty: string
+  noResults: string
+  loading: string
+  failure: string
+  view: string
+  download: string
+  openConversation: string
+  sourceFilterAll: string
+  sourceFilterCustomer: string
+  sourceFilterTeam: string
+  sortMostRecent: string
+  sortOldest: string
+  clearFilters: string
+  total: (count: number) => string
+  page: (current: number, last: number) => string
+}
+
+export const DEFAULT_DOCUMENTS_LIBRARY_LABELS: DocumentsLibraryLabels = {
+  title: 'Documentos',
+  searchPlaceholder: 'Buscar por nome do arquivo ou telefone',
+  empty: 'Nenhum arquivo trocado ainda.',
+  noResults: 'Nenhum arquivo encontrado para os filtros aplicados',
+  loading: 'Carregando arquivos…',
+  failure: 'Não foi possível carregar os arquivos.',
+  view: 'Visualizar',
+  download: 'Baixar',
+  openConversation: 'Abrir conversa',
+  sourceFilterAll: 'Todas as origens',
+  sourceFilterCustomer: 'Cliente',
+  sourceFilterTeam: 'Equipe',
+  sortMostRecent: 'Mais recentes',
+  sortOldest: 'Mais antigos',
+  clearFilters: 'Limpar filtros',
+  total: (count: number) => `${count} arquivo${count === 1 ? '' : 's'}`,
+  page: (current: number, last: number) => `${current} / ${last}`,
+}
+
+export interface DocumentsLibraryClassNames {
+  root: string
+  title: string
+  filters: string
+  search: string
+  sourceSelect: string
+  sortButton: string
+  clearButton: string
+  status: string
+  list: string
+  item: string
+  conversationLink: string
+  filename: string
+  meta: string
+  pagination: string
+}
+
+export interface DocumentsLibraryProps {
+  /** Itens por página. O total vem do servidor. */
+  perPage?: number
+  /** Abrir a conversa de origem. Ausente, o número aparece como texto e não como link. */
+  onOpenConversation?: (conversationId: string) => void
+  labels?: Partial<DocumentsLibraryLabels>
+  className?: string
+  classNames?: Partial<DocumentsLibraryClassNames>
+}
+
+const TEAM_SOURCES = new Set(['agent', 'bot'])
+const DEFAULT_PER_PAGE = 20
+
+export function DocumentsLibrary({
+  perPage = DEFAULT_PER_PAGE,
+  onOpenConversation,
+  labels: labelsOverride,
+  className,
+  classNames,
+}: DocumentsLibraryProps) {
+  const labels = { ...DEFAULT_DOCUMENTS_LIBRARY_LABELS, ...labelsOverride }
+  const context = useConversations()
+  const [search, setSearch] = useState('')
+  const [sourceFilter, setSourceFilter] = useState<DocumentSourceFilter>(DOCUMENT_SOURCE_FILTER.ALL)
+  const [sortDirection, setSortDirection] = useState<'asc' | 'desc'>('desc')
+  const [page, setPage] = useState(1)
+  const [documents, setDocuments] = useState<readonly CompanyDocument[]>([])
+  const [total, setTotal] = useState(0)
+  const [loading, setLoading] = useState(false)
+  const [failed, setFailed] = useState(false)
+
+  const hasFilters = search !== '' || sourceFilter !== DOCUMENT_SOURCE_FILTER.ALL || sortDirection !== 'desc'
+  const lastPage = Math.max(1, Math.ceil(total / perPage))
+  const fetchAll = context?.api.getAllDocuments
+
+  useEffect(() => {
+    if (!fetchAll) return
+    let active = true
+    setLoading(true)
+    setFailed(false)
+
+    void fetchAll({
+      search,
+      page,
+      limit: perPage,
+      sortDirection,
+      ...(sourceFilter === DOCUMENT_SOURCE_FILTER.ALL ? {} : { source: sourceFilter }),
+    })
+      .then((result) => {
+        // `active` evita que uma resposta antiga sobrescreva a nova: digitar rápido na busca dispara
+        // várias chamadas e a ordem de retorno não é garantida.
+        if (!active) return
+        setDocuments(result.documents)
+        setTotal(result.total)
+      })
+      .catch(() => {
+        if (active) setFailed(true)
+      })
+      .finally(() => {
+        if (active) setLoading(false)
+      })
+
+    return () => {
+      active = false
+    }
+  }, [fetchAll, search, sourceFilter, sortDirection, page, perPage])
+
+  function applyFilter(change: () => void): void {
+    change()
+    setPage(1)
+  }
+
+  async function handleOpen(uploadId: string, disposition: 'inline' | 'attachment'): Promise<void> {
+    const url = await context?.api.getDocumentUrl(uploadId, disposition)
+    if (url) window.open(url, '_blank', 'noopener,noreferrer')
+  }
+
+  // Host sem `getAllDocuments` não tem o que mostrar aqui — some, em vez de renderizar vazio para
+  // sempre e fazer parecer que a empresa não tem arquivo nenhum.
+  if (!fetchAll) return null
+
+  return (
+    <div className={cn('space-y-3', classNames?.root, className)}>
+      <h2 className={cn('text-lg font-semibold', classNames?.title)}>{labels.title}</h2>
+
+      <div className={cn('flex flex-wrap items-center gap-2', classNames?.filters)}>
+        <input
+          type="search"
+          value={search}
+          onChange={(event) => applyFilter(() => setSearch(event.target.value))}
+          placeholder={labels.searchPlaceholder}
+          aria-label={labels.searchPlaceholder}
+          className={cn('w-full rounded-md border px-3 py-2 text-sm sm:w-64', classNames?.search)}
+        />
+
+        <select
+          value={sourceFilter}
+          onChange={(event) => applyFilter(() => setSourceFilter(event.target.value as DocumentSourceFilter))}
+          aria-label={labels.sourceFilterAll}
+          className={cn('w-full rounded-md border px-2 py-2 text-sm sm:w-40', classNames?.sourceSelect)}
+        >
+          <option value={DOCUMENT_SOURCE_FILTER.ALL}>{labels.sourceFilterAll}</option>
+          <option value={DOCUMENT_SOURCE_FILTER.CUSTOMER}>{labels.sourceFilterCustomer}</option>
+          <option value={DOCUMENT_SOURCE_FILTER.TEAM}>{labels.sourceFilterTeam}</option>
+        </select>
+
+        <button
+          type="button"
+          onClick={() => applyFilter(() => setSortDirection(sortDirection === 'desc' ? 'asc' : 'desc'))}
+          className={cn('cv-header-action inline-flex items-center gap-1', classNames?.sortButton)}
+        >
+          <ArrowUpDown size={14} />
+          {sortDirection === 'desc' ? labels.sortMostRecent : labels.sortOldest}
+        </button>
+
+        {hasFilters ? (
+          <button
+            type="button"
+            onClick={() =>
+              applyFilter(() => {
+                setSearch('')
+                setSourceFilter(DOCUMENT_SOURCE_FILTER.ALL)
+                setSortDirection('desc')
+              })
+            }
+            className={cn('cv-header-action', classNames?.clearButton)}
+          >
+            {labels.clearFilters}
+          </button>
+        ) : null}
+      </div>
+
+      {loading ? <p className={cn('text-sm text-gray-500', classNames?.status)}>{labels.loading}</p> : null}
+      {failed ? (
+        <p role="alert" className={cn('text-sm text-red-600 dark:text-red-400', classNames?.status)}>
+          {labels.failure}
+        </p>
+      ) : null}
+      {!loading && !failed && documents.length === 0 ? (
+        <p className={cn('text-sm text-gray-500', classNames?.status)}>
+          {hasFilters ? labels.noResults : labels.empty}
+        </p>
+      ) : null}
+
+      <ul className={cn('space-y-2', classNames?.list)}>
+        {documents.map((document) => {
+          const isFromCustomer = !TEAM_SOURCES.has(document.source)
+          const SourceIcon = isFromCustomer ? Users : Bot
+
+          return (
+            <li
+              key={`${document.conversationId}:${document.id}`}
+              className={cn(
+                'flex items-center justify-between gap-3 rounded-lg border px-3 py-2 dark:border-gray-700',
+                classNames?.item,
+              )}
+            >
+              <div className="flex min-w-0 flex-1 items-center gap-3">
+                <FileIcon filename={document.filename} mimeType={document.mimeType} />
+                <div className="min-w-0 flex-1">
+                  <div className={cn('truncate text-sm font-medium', classNames?.filename)} title={document.filename}>
+                    {document.filename}
+                  </div>
+                  <div className={cn('flex flex-wrap items-center gap-x-2 text-xs text-gray-500', classNames?.meta)}>
+                    <span className="inline-flex items-center gap-1">
+                      <SourceIcon size={11} />
+                      {isFromCustomer ? labels.sourceFilterCustomer : labels.sourceFilterTeam}
+                    </span>
+                    <span>·</span>
+                    <span>{formatDateTime(document.linkedAt)}</span>
+                    <span>·</span>
+                    <span>{formatFileSize(document.sizeBytes)}</span>
+                  </div>
+                </div>
+              </div>
+
+              {/* A conversa de origem é o dado que só esta tela tem. Vira botão quando o host sabe
+                  navegar; sem handler, fica texto — link que não leva a lugar nenhum é pior. */}
+              {onOpenConversation ? (
+                <button
+                  type="button"
+                  onClick={() => onOpenConversation(document.conversationId)}
+                  title={labels.openConversation}
+                  className={cn('cv-header-action inline-flex shrink-0 items-center gap-1', classNames?.conversationLink)}
+                >
+                  <MessageSquare size={12} />
+                  {formatPhone(document.conversationId)}
+                </button>
+              ) : (
+                <span className={cn('shrink-0 text-xs text-gray-500', classNames?.conversationLink)}>
+                  {formatPhone(document.conversationId)}
+                </span>
+              )}
+
+              <div className="flex shrink-0 gap-1">
+                <button
+                  type="button"
+                  onClick={() => void handleOpen(document.id, 'inline')}
+                  title={labels.view}
+                  aria-label={`${labels.view}: ${document.filename}`}
+                  className="cv-header-icon"
+                >
+                  <Eye size={14} />
+                </button>
+                <button
+                  type="button"
+                  onClick={() => void handleOpen(document.id, 'attachment')}
+                  title={labels.download}
+                  aria-label={`${labels.download}: ${document.filename}`}
+                  className="cv-header-icon"
+                >
+                  <Download size={14} />
+                </button>
+              </div>
+            </li>
+          )
+        })}
+      </ul>
+
+      {total > perPage ? (
+        <div className={cn('flex items-center justify-between border-t pt-2 text-xs dark:border-gray-700', classNames?.pagination)}>
+          <span className="text-gray-400">{labels.total(total)}</span>
+          <div className="flex items-center gap-2">
+            <button
+              type="button"
+              onClick={() => setPage(page - 1)}
+              disabled={page <= 1}
+              className="cv-header-icon disabled:opacity-40"
+            >
+              ‹
+            </button>
+            <span className="text-gray-500">{labels.page(page, lastPage)}</span>
+            <button
+              type="button"
+              onClick={() => setPage(page + 1)}
+              disabled={page >= lastPage}
+              className="cv-header-icon disabled:opacity-40"
+            >
+              ›
+            </button>
+          </div>
+        </div>
+      ) : null}
+    </div>
+  )
+}

package/src/FileIcon.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'bun:test'
+
+import { resolveFileIconExtension } from './FileIcon'
+
+describe('resolveFileIconExtension', () => {
+  // Regressão: o painel de documentos passava só o mimeType, e o do Office é longo
+  // (`application/vnd.openxmlformats-officedocument.wordprocessingml.document`), então docx, doc,
+  // xlsx e xls apareciam todos com o ícone genérico cinza.
+  const OFFICE_MIME_TYPES = [
+    {
+      filename: 'contrato.docx',
+      mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      expected: 'docx',
+    },
+    { filename: 'procuracao.doc', mimeType: 'application/msword', expected: 'doc' },
+    {
+      filename: 'pedido.xlsx',
+      mimeType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+      expected: 'xlsx',
+    },
+    { filename: 'tabela.xls', mimeType: 'application/vnd.ms-excel', expected: 'xls' },
+  ]
+
+  for (const testCase of OFFICE_MIME_TYPES) {
+    it(`resolve ${testCase.expected} pelo nome, já que o mimeType do Office não bate`, () => {
+      expect(resolveFileIconExtension(testCase.filename, testCase.mimeType)).toBe(testCase.expected)
+    })
+  }
+
+  it('resolve pelo mimeType quando o nome não tem extensão conhecida', () => {
+    expect(resolveFileIconExtension(undefined, 'application/pdf')).toBe('pdf')
+    expect(resolveFileIconExtension('recibo', 'application/zip')).toBe('zip')
+  })
+
+  it('devolve algo fora do mapa para tipo desconhecido, caindo no ícone genérico', () => {
+    expect(resolveFileIconExtension('backup', 'application/octet-stream')).toBe('octet-stream')
+  })
+
+  // Imagem, vídeo e áudio entram na biblioteca junto dos documentos — o backend linka as cinco
+  // espécies de mídia (image/audio/video/document/sticker), não só `document`.
+  const MEDIA_TYPES = [
+    { filename: 'foto.jpg', mimeType: 'image/jpeg', expected: 'jpg' },
+    { filename: 'prateleira.png', mimeType: 'image/png', expected: 'png' },
+    { filename: 'video-do-produto.mp4', mimeType: 'video/mp4', expected: 'mp4' },
+    { filename: 'antigo.3gp', mimeType: 'video/3gp', expected: '3gp' },
+    { filename: 'musica.mp3', mimeType: 'audio/mpeg', expected: 'mp3' },
+    { filename: 'recado.m4a', mimeType: 'audio/mp4', expected: 'm4a' },
+    { filename: 'lista-compras.txt', mimeType: 'text/plain', expected: 'txt' },
+    { filename: 'planilha.csv', mimeType: 'text/csv', expected: 'csv' },
+    {
+      filename: 'apresentacao.pptx',
+      mimeType: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+      expected: 'pptx',
+    },
+  ]
+
+  for (const testCase of MEDIA_TYPES) {
+    it(`resolve ${testCase.expected}`, () => {
+      expect(resolveFileIconExtension(testCase.filename, testCase.mimeType)).toBe(testCase.expected)
+    })
+  }
+
+  // Áudio e sticker chegam da Meta sem nome de arquivo: o backend salva o id da mídia como rótulo,
+  // então a única pista de tipo é o mimeType.
+  it('resolve pela família quando o nome é o id da mídia, sem extensão', () => {
+    expect(resolveFileIconExtension('wamid-abc123', 'image/webp')).toBe('image')
+    expect(resolveFileIconExtension('wamid-abc123', 'video/mp4')).toBe('video')
+    expect(resolveFileIconExtension('wamid-abc123', 'audio/aac')).toBe('audio')
+  })
+
+  // `audio/ogg; codecs=opus` é o formato do áudio de WhatsApp. Com o parâmetro colado, o subtipo
+  // viria "ogg; codecs=opus" e o áudio cairia no ícone genérico.
+  it('descarta parâmetro do mimeType', () => {
+    expect(resolveFileIconExtension('wamid-audio', 'audio/ogg; codecs=opus')).toBe('audio')
+  })
+
+  // Pelo subtipo, `audio/mp4` casaria a chave `mp4` — que é vídeo. A família vem primeiro
+  // justamente para um m4a não aparecer com ícone de filme.
+  it('não confunde audio/mp4 com vídeo', () => {
+    expect(resolveFileIconExtension(undefined, 'audio/mp4')).toBe('audio')
+    expect(resolveFileIconExtension(undefined, 'video/mp4')).toBe('video')
+  })
+})

package/src/FileIcon.tsx

@@ -1,4 +1,15 @@
-import { FileArchive, FileSpreadsheet, FileText, File as FileGeneric } from 'lucide-react'
+import {
+  FileArchive,
+  FileAudio,
+  FileImage,
+  FileSpreadsheet,
+  FileText,
+  FileVideo,
+  File as FileGeneric,
+  Presentation,
+} from 'lucide-react'
+
+import { cn } from './lib/cn'
 
 export interface FileIconProps {
   filename?: string
@@ -7,27 +18,93 @@ export interface FileIconProps {
   className?: string
 }
 
-const EXTENSION_STYLE: Record<string, { Icon: typeof FileText; colorClass: string }> = {
+type IconStyle = { Icon: typeof FileText; colorClass: string }
+
+// Um estilo por família, reaproveitado por todas as extensões dela: assim o ícone de um `.jpg`
+// resolvido pelo nome é o mesmo de um `image/jpeg` resolvido pelo mimeType. Com cor por extensão, a
+// mesma foto trocaria de cor conforme o dado que chegou junto.
+const IMAGE_STYLE: IconStyle = { Icon: FileImage, colorClass: 'text-violet-500' }
+const VIDEO_STYLE: IconStyle = { Icon: FileVideo, colorClass: 'text-fuchsia-500' }
+const AUDIO_STYLE: IconStyle = { Icon: FileAudio, colorClass: 'text-amber-500' }
+const SHEET_STYLE: IconStyle = { Icon: FileSpreadsheet, colorClass: 'text-green-600' }
+const WORD_STYLE: IconStyle = { Icon: FileText, colorClass: 'text-blue-500' }
+const SLIDES_STYLE: IconStyle = { Icon: Presentation, colorClass: 'text-orange-600' }
+const TEXT_STYLE: IconStyle = { Icon: FileText, colorClass: 'text-gray-500' }
+
+const EXTENSION_STYLE: Record<string, IconStyle> = {
   pdf: { Icon: FileText, colorClass: 'text-red-500' },
-  doc: { Icon: FileText, colorClass: 'text-blue-500' },
-  docx: { Icon: FileText, colorClass: 'text-blue-500' },
-  xls: { Icon: FileSpreadsheet, colorClass: 'text-green-600' },
-  xlsx: { Icon: FileSpreadsheet, colorClass: 'text-green-600' },
+  doc: WORD_STYLE,
+  docx: WORD_STYLE,
+  xls: SHEET_STYLE,
+  xlsx: SHEET_STYLE,
+  csv: SHEET_STYLE,
+  ppt: SLIDES_STYLE,
+  pptx: SLIDES_STYLE,
   zip: { Icon: FileArchive, colorClass: 'text-orange-500' },
+  txt: TEXT_STYLE,
+  plain: TEXT_STYLE,
+
+  image: IMAGE_STYLE,
+  jpg: IMAGE_STYLE,
+  jpeg: IMAGE_STYLE,
+  png: IMAGE_STYLE,
+  webp: IMAGE_STYLE,
+  gif: IMAGE_STYLE,
+  heic: IMAGE_STYLE,
+
+  video: VIDEO_STYLE,
+  mp4: VIDEO_STYLE,
+  '3gp': VIDEO_STYLE,
+  '3gpp': VIDEO_STYLE,
+  mov: VIDEO_STYLE,
+  webm: VIDEO_STYLE,
+
+  audio: AUDIO_STYLE,
+  mp3: AUDIO_STYLE,
+  mpeg: AUDIO_STYLE,
+  ogg: AUDIO_STYLE,
+  oga: AUDIO_STYLE,
+  opus: AUDIO_STYLE,
+  aac: AUDIO_STYLE,
+  amr: AUDIO_STYLE,
+  m4a: AUDIO_STYLE,
+  wav: AUDIO_STYLE,
 }
 
-function getExtension(filename?: string, mimeType?: string): string {
+const MEDIA_FAMILIES = new Set(['image', 'video', 'audio'])
+
+/**
+ * A chave de estilo do arquivo, na ordem em que cada dado é confiável.
+ *
+ * 1. **extensão do nome** — o mimeType do Office é longo (`…wordprocessingml.document`) e nunca
+ *    casaria, então quem olhasse só o mimeType perderia o ícone de Word e de Excel;
+ * 2. **família do mimeType** (`image/`, `video/`, `audio/`) — tem de vir ANTES do subtipo por causa
+ *    de `audio/mp4`: pelo subtipo, um áudio m4a ganharia o ícone de vídeo;
+ * 3. **subtipo** — cobre `application/pdf` e `application/zip`, que chegam sem nome de arquivo.
+ *
+ * Áudio de WhatsApp chega como `audio/ogg; codecs=opus`; o parâmetro depois do `;` é descartado,
+ * senão o subtipo viria `ogg; codecs=opus` e não casaria nada.
+ *
+ * Exportada para teste: é a regra que já regrediu uma vez no painel de documentos.
+ */
+export function resolveFileIconExtension(filename?: string, mimeType?: string): string {
   const fromFilename = filename?.split('.').pop()?.toLowerCase()
   if (fromFilename && EXTENSION_STYLE[fromFilename]) return fromFilename
-  return mimeType?.split('/')[1]?.toLowerCase() ?? ''
+
+  const [family, subtype] = (mimeType ?? '').split(';')[0]!.toLowerCase().split('/')
+  if (family && MEDIA_FAMILIES.has(family)) return family
+
+  return subtype ?? ''
 }
 
 // Melhoria sobre a paridade da bolha de documento (T6.7 usava um único ícone genérico
 // para qualquer tipo de arquivo) — ícone e cor variam por extensão/mimeType.
-export function FileIcon({ filename, mimeType, size = 20, className = '' }: FileIconProps) {
-  const extension = getExtension(filename, mimeType)
+export function FileIcon({ filename, mimeType, size = 20, className }: FileIconProps) {
+  const extension = resolveFileIconExtension(filename, mimeType)
   const style = EXTENSION_STYLE[extension] ?? { Icon: FileGeneric, colorClass: 'text-gray-500' }
   const { Icon, colorClass } = style
 
-  return <Icon size={size} className={`${colorClass} ${className}`.trim()} />
+  // `cn` em vez de concatenar: a cor por extensão é a base, e produto que passa `text-*` precisa
+  // ganhar dela — concatenado, quem vence é a ordem no CSS gerado, não a intenção de quem chamou.
+  return <Icon size={size} className={cn(colorClass, className)} />
 }

package/src/Lightbox.tsx

@@ -1,16 +1,31 @@
+export interface LightboxLabels {
+  /** Texto alternativo quando a imagem não tem legenda — sem ele o leitor de tela anuncia a URL. */
+  imageAlt: string
+  close: string
+}
+
 export interface LightboxProps {
   imageUrl: string
   caption?: string
   onClose: () => void
+  labels?: Partial<LightboxLabels>
 }
 
-export function Lightbox({ imageUrl, caption, onClose }: LightboxProps) {
+export const DEFAULT_LIGHTBOX_LABELS: LightboxLabels = {
+  imageAlt: 'Imagem',
+  close: 'Fechar',
+}
+
+export function Lightbox({ imageUrl, caption, onClose, labels }: LightboxProps) {
+  const imageAltLabel = labels?.imageAlt ?? DEFAULT_LIGHTBOX_LABELS.imageAlt
+  const closeLabel = labels?.close ?? DEFAULT_LIGHTBOX_LABELS.close
+
   return (
     <div className="fixed inset-0 z-50 bg-black/85 flex items-center justify-center p-4" onClick={onClose}>
       <div className="max-w-[90vw] max-h-[90vh] flex flex-col items-center" onClick={(e) => e.stopPropagation()}>
-        <img src={imageUrl} alt={caption ?? 'Image'} className="max-w-full max-h-[80vh] object-contain rounded-lg" />
+        <img src={imageUrl} alt={caption ?? imageAltLabel} className="max-w-full max-h-[80vh] object-contain rounded-lg" />
         {caption && <p className="text-white text-sm mt-3 text-center">{caption}</p>}
-        <button onClick={onClose} className="mt-4 px-4 py-2 bg-white/20 text-white rounded-lg hover:bg-white/30 transition-colors">Fechar</button>
+        <button onClick={onClose} className="mt-4 px-4 py-2 bg-white/20 text-white rounded-lg hover:bg-white/30 transition-colors">{closeLabel}</button>
       </div>
     </div>
   )

package/src/MediaRenderer.tsx

@@ -3,6 +3,7 @@ import { AudioPlayer } from './AudioPlayer'
 import { FileIcon } from './FileIcon'
 import { useConversationLocales } from './ConversationLocalesProvider'
 import { formatFileSize } from './lib/format'
+import { cn } from './lib/cn'
 import type { MessagePayload } from './types'
 
 function resolveMediaSource(message: MessagePayload): string | null {
@@ -30,6 +31,8 @@ export interface MediaRendererProps {
   // loadUrl/loadMedia de financiamento-imobiliario-bot/apps/web/src/components/MessageBubble.tsx,
   // porém delegando o fetch ao host em vez de hardcodar `/uploads/:id/download-url`.
   onResolveUrl?: ResolveMediaUrl
+  /** Aplicado no wrapper de cada tipo de mídia — imagem, vídeo, áudio e documento. */
+  className?: string
 }
 
 function useLazyMediaUrl(message: MessagePayload, onResolveUrl?: ResolveMediaUrl) {
@@ -55,7 +58,7 @@ function useLazyMediaUrl(message: MessagePayload, onResolveUrl?: ResolveMediaUrl
   return { url, loading, error, load }
 }
 
-export function MediaRenderer({ message, onLightbox, onResolveUrl }: MediaRendererProps) {
+export function MediaRenderer({ message, onLightbox, onResolveUrl, className }: MediaRendererProps) {
   const { bubble } = useConversationLocales()
   const eagerSrc = resolveMediaSource(message)
   const lazy = useLazyMediaUrl(message, onResolveUrl)
@@ -126,7 +129,7 @@ export function MediaRenderer({ message, onLightbox, onResolveUrl }: MediaRender
       const typeLabel = message.mimeType?.split('/')[1]?.toUpperCase() ?? 'FILE'
       const sizeLabel = message.sizeBytes ? formatFileSize(message.sizeBytes) : null
       return (
-        <div className="flex items-center gap-3 min-w-[200px]">
+        <div className={cn('flex items-center gap-3 min-w-[200px]', className)}>
           <div className="w-10 h-10 bg-gray-200 rounded-lg flex items-center justify-center flex-shrink-0">
             <FileIcon filename={message.filename} mimeType={message.mimeType} />
           </div>

package/src/MessageBubble.tsx

@@ -1,4 +1,4 @@
-import { useState } from 'react'
+import { useMemo, useState } from 'react'
 import { Check } from 'lucide-react'
 import type { MessagePayload } from './types'
 import { useConversationLocales } from './ConversationLocalesProvider'
@@ -7,6 +7,8 @@ import { MediaRenderer, type ResolveMediaUrl } from './MediaRenderer'
 import { Lightbox } from './Lightbox'
 import { parseWhatsAppFormatting } from './lib/whatsapp-formatting'
 import { cn } from './lib/cn'
+import { createMediaUrlResolver } from './lib/createMediaUrlResolver'
+import { useConversations } from './providers/ConversationsProvider'
 import { formatTimestamp, formatDateTime } from './lib/format'
 
 export interface MessageBubbleProps {
@@ -17,6 +19,10 @@ export interface MessageBubbleProps {
   isSelecting?: boolean
   isSelected?: boolean
   onToggleSelect?: () => void
+  /**
+   * Como buscar a mídia da mensagem. Ausente, o balão usa o `ConversationsApi` do
+   * `ConversationsProvider` — passe apenas para sobrescrever (cache próprio, CDN, proxy do host).
+   */
   onResolveMediaUrl?: ResolveMediaUrl
   className?: string
 }
@@ -43,6 +49,16 @@ export function MessageBubble({
 }: MessageBubbleProps) {
   const { bubble, selection } = useConversationLocales()
   const [lightboxSrc, setLightboxSrc] = useState<string | null>(null)
+  const context = useConversations()
+
+  // Resolvedor pelo contexto quando o host não passa um: o contrato já declara `getDocumentUrl` e
+  // `getMediaProxyUrl`, então exigir que cada projeto ligasse esse fio só garantia que a mídia não
+  // carregasse em quem esquecesse. `useMemo` porque o resolvedor é a identidade de que o
+  // `MediaRenderer` depende para não refazer busca a cada render.
+  const resolveMediaUrl = useMemo(
+    () => onResolveMediaUrl ?? (context?.api ? createMediaUrlResolver(context.api) : undefined),
+    [onResolveMediaUrl, context?.api],
+  )
 
   const bubbleColor = BUBBLE_COLOR[message.sender] ?? BUBBLE_COLOR.customer
   const hasError = message.status === 'failed'
@@ -115,7 +131,7 @@ export function MessageBubble({
         )}
 
         {isMedia ? (
-          <MediaRenderer message={message} onLightbox={setLightboxSrc} onResolveUrl={onResolveMediaUrl} />
+          <MediaRenderer message={message} onLightbox={setLightboxSrc} onResolveUrl={resolveMediaUrl} />
         ) : (
           <>
             {isTemplate && (