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

package/src/ConversationListItem.tsx

@@ -3,8 +3,21 @@ import { Avatar } from './Avatar'
 import { contactFlag, formatContactHandle } from './conversationChannel'
 import type { ConversationSummary } from './providers/types'
 
+export interface ConversationListItemLabels {
+  /** Tooltip do ponto vermelho: a janela de atendimento de 24h já fechou. */
+  expiredWindow: string
+  /** Tooltip do ponto laranja: a janela de atendimento está perto de fechar. */
+  warningWindow: string
+}
+
+export const DEFAULT_CONVERSATION_LIST_ITEM_LABELS: ConversationListItemLabels = {
+  expiredWindow: 'Janela expirada',
+  warningWindow: 'Janela próxima do fim',
+}
+
 export interface ConversationListItemProps {
   conversation: ConversationSummary
+  labels?: Partial<ConversationListItemLabels>
   active?: boolean
   selected?: boolean
   onClick?: () => void
@@ -92,7 +105,10 @@ export const ConversationListItem = ({
   onSelect,
   showDivider = true,
   highlightActive = true,
+  labels,
 }: ConversationListItemProps) => {
+  const expiredWindowLabel = labels?.expiredWindow ?? DEFAULT_CONVERSATION_LIST_ITEM_LABELS.expiredWindow
+  const warningWindowLabel = labels?.warningWindow ?? DEFAULT_CONVERSATION_LIST_ITEM_LABELS.warningWindow
   const isActive = active || selected
   const windowStatus = useMemo(() => getWindowStatus(conversation.lastInboundAt), [conversation.lastInboundAt])
   const preview = useMemo(() => lastMessagePreview(conversation), [conversation.lastContent])
@@ -134,10 +150,10 @@ export const ConversationListItem = ({
             {!conversation.clientName && flag ? <span aria-hidden>{flag}</span> : null}
             <span className="text-[16px] text-[#111b21] truncate">{name}</span>
             {windowStatus && windowStatus.label === 'expired' && (
-              <span className="w-2 h-2 rounded-full bg-red-500 flex-shrink-0" title="Janela expirada" />
+              <span className="w-2 h-2 rounded-full bg-red-500 flex-shrink-0" title={expiredWindowLabel} />
             )}
             {windowStatus && windowStatus.label === 'warning' && (
-              <span className="w-2 h-2 rounded-full bg-orange-500 flex-shrink-0" title="Janela próxima do fim" />
+              <span className="w-2 h-2 rounded-full bg-orange-500 flex-shrink-0" title={warningWindowLabel} />
             )}
           </div>
           {timestamp && (

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

@@ -33,6 +33,51 @@ describe('resolveFileIconExtension', () => {
   })
 
   it('devolve algo fora do mapa para tipo desconhecido, caindo no ícone genérico', () => {
-    expect(resolveFileIconExtension('lista-compras.txt', 'text/plain')).toBe('plain')
+    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,13 @@
-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'
 
@@ -9,26 +18,83 @@ 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,
 }
 
+const MEDIA_FAMILIES = new Set(['image', 'video', 'audio'])
+
 /**
- * O nome do arquivo tem precedência sobre o mimeType porque o mapa é indexado por extensão curta:
- * o mimeType do Office é longo (`…wordprocessingml.document`) e nunca casaria, então quem passa só
- * mimeType perde o ícone de Word e de Excel.
+ * 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

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/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 && (

package/src/MessageComposer.tsx

@@ -3,7 +3,20 @@ import type { ConversationsFeatures } from './types'
 import { cn } from './lib/cn'
 import { EmojiPicker } from './EmojiPicker'
 
+export interface MessageComposerLabels {
+  emoji: string
+  attach: string
+  send: string
+}
+
+export const DEFAULT_MESSAGE_COMPOSER_LABELS: MessageComposerLabels = {
+  emoji: 'Emoji',
+  attach: 'Anexar',
+  send: 'Enviar',
+}
+
 export interface MessageComposerProps {
+  labels?: Partial<MessageComposerLabels>
   onSend: (text: string) => void
   onAttach?: (file: File) => void
   value?: string
@@ -42,7 +55,11 @@ export const MessageComposer = ({
   acceptedFileTypes = DEFAULT_ACCEPTED_FILE_TYPES,
   className,
   classNames,
+  labels,
 }: MessageComposerProps) => {
+  const emojiLabel = labels?.emoji ?? DEFAULT_MESSAGE_COMPOSER_LABELS.emoji
+  const attachLabel = labels?.attach ?? DEFAULT_MESSAGE_COMPOSER_LABELS.attach
+  const sendLabel = labels?.send ?? DEFAULT_MESSAGE_COMPOSER_LABELS.send
   const [internalText, setInternalText] = useState('')
   const [showEmoji, setShowEmoji] = useState(false)
   const [attachments, setAttachments] = useState<FilePreview[]>([])
@@ -168,7 +185,7 @@ export const MessageComposer = ({
       <div className={cn('flex items-end gap-1.5 rounded-xl bg-white px-3 py-2', classNames?.field)}>
         {showEmojiButton && (
           <div className="relative flex-shrink-0">
-            <button onClick={() => setShowEmoji(v => !v)} className="w-9 h-9 flex items-center justify-center rounded-full text-gray-500 hover:bg-gray-200 transition-colors" aria-label="Emoji">
+            <button onClick={() => setShowEmoji(v => !v)} className="w-9 h-9 flex items-center justify-center rounded-full text-gray-500 hover:bg-gray-200 transition-colors" aria-label={emojiLabel}>
               <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2"><circle cx="12" cy="12" r="10"/><path d="M8 14s1.5 2 4 2 4-2 4-2"/><circle cx="9" cy="9" r="0.5" fill="currentColor"/><circle cx="15" cy="9" r="0.5" fill="currentColor"/></svg>
             </button>
             {showEmoji && (
@@ -194,7 +211,7 @@ export const MessageComposer = ({
         {showAttachButton && (
           <>
             <input ref={fileInputRef} type="file" multiple accept={acceptedFileTypes} onChange={handleFileChange} className="hidden" />
-            <button onClick={() => fileInputRef.current?.click()} className="w-9 h-9 flex items-center justify-center rounded-full text-gray-500 hover:bg-gray-200 flex-shrink-0 transition-colors" aria-label="Anexar">
+            <button onClick={() => fileInputRef.current?.click()} className="w-9 h-9 flex items-center justify-center rounded-full text-gray-500 hover:bg-gray-200 flex-shrink-0 transition-colors" aria-label={attachLabel}>
               <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2"><path d="M21.44 11.05l-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 5.66 5.66l-9.2 9.19a2 2 0 0 1-2.83-2.83l8.49-8.48"/></svg>
             </button>
           </>
@@ -208,7 +225,7 @@ export const MessageComposer = ({
               ? 'bg-[#00a884] text-white hover:bg-[#06cf9c] shadow-sm'
               : 'bg-gray-200 text-gray-400 cursor-not-allowed'
           }`}
-          aria-label="Enviar"
+          aria-label={sendLabel}
         >
           <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor"><path d="M2.01 21L23 12 2.01 3 2 10l15 2-15 2z"/></svg>
         </button>