@adatechnology/conversations-ui 0.1.0-rc.26 → 0.1.0-rc.28

package/src/ConversationHeader.tsx

@@ -6,14 +6,29 @@
  * papel do pacote saber a rota de cada host. Quem passa os handlers é o produto.
  */
 
-import { useState } from 'react'
+import { useRef, useState, type ReactNode } from 'react'
+import { ArrowLeft, Bot, Download, FileText, Headset, MoreVertical, UserRound, X } from 'lucide-react'
 
 import type { ConversationSummary } from './providers/types'
 import { capabilitiesOf, contactFlag, formatContactHandle } from './conversationChannel'
 import { cn } from './lib/cn'
+import { ICON_SIZE_ACTION, ICON_SIZE_INLINE } from './icon.constant'
+import { useContainerWidth } from './hooks/useContainerWidth'
 import { Avatar } from './Avatar'
 import { ChannelIcon } from './ChannelIcon'
 
+/**
+ * Larguras do próprio cabeçalho (em px) que decidem o quanto ele recolhe. São da faixa, não da
+ * janela: com a prévia do simulador aberta a coluna fica com metade da tela, e pelo breakpoint da
+ * janela o cabeçalho continuava desenhando tudo — sobrava uma letra do nome do cliente.
+ *
+ * Abaixo da primeira, os utilitários (ícones de consulta) viram itens do menu ⋮ e o telefone volta a
+ * caber; abaixo da segunda, até as ações escritas entram no menu, porque nem elas cabem sem comer o
+ * nome. Quem identifica a conversa é o nome — ele é o último a ceder espaço.
+ */
+const HEADER_UTILITIES_MIN_WIDTH = 720
+const HEADER_ACTIONS_MIN_WIDTH = 600
+
 export interface ConversationHeaderLabels {
   botMode: string
   humanMode: string
@@ -27,8 +42,10 @@ export interface ConversationHeaderLabels {
 }
 
 export const DEFAULT_CONVERSATION_HEADER_LABELS: ConversationHeaderLabels = {
-  botMode: '🤖 atendimento automático',
-  humanMode: '🧑‍💼 atendimento humano',
+  // Sem emoji no rótulo: quem desenha o modo é o ícone ao lado, e o emoji embutido no texto voltava
+  // a aparecer no tooltip e no leitor de tela como um caractere sem nome.
+  botMode: 'atendimento automático',
+  humanMode: 'atendimento humano',
   returnToBot: 'Devolver ao bot',
   finish: 'Finalizar',
   takeover: 'Assumir atendimento',
@@ -59,13 +76,26 @@ export interface ConversationHeaderClassNames {
  */
 export interface ConversationHeaderUtility {
   key: string
-  /** Emoji, para casar com os utilitários nativos do cabeçalho. */
-  icon: string
+  /** Ícone da biblioteca (lucide), no tamanho dos utilitários nativos: `<Play size={16} />`. */
+  icon: ReactNode
   label: string
   run: () => void
   active?: boolean
 }
 
+/** Utilitário já resolvido para desenho: o `active` opcional do contrato vira estado explícito. */
+type ResolvedUtility = ConversationHeaderUtility & { active: boolean }
+
+/** Ação de atendimento pronta para virar botão na faixa ou item do menu ⋮. */
+type HeaderAction = {
+  key: string
+  icon: ReactNode
+  label: string
+  hint: string
+  run: () => void
+  className: string
+}
+
 export interface ConversationHeaderProps {
   conversation: ConversationSummary
   busy?: boolean
@@ -105,42 +135,92 @@ export function ConversationHeader({
   const flag = contactFlag({ handle, channel: conversation.channel })
   const capabilities = capabilitiesOf(conversation.channel)
   const [menuOpen, setMenuOpen] = useState(false)
+  const headerRef = useRef<HTMLElement>(null)
+  const headerWidth = useContainerWidth(headerRef)
+
+  // Sem medida ainda (SSR, primeiro render) o cabeçalho nasce completo: é o layout correto na maior
+  // parte dos casos, e recolher depois não tira nada do lugar de quem já estava lendo.
+  const showsUtilitiesInline = headerWidth === undefined || headerWidth >= HEADER_UTILITIES_MIN_WIDTH
+  const showsActionsInline = headerWidth === undefined || headerWidth >= HEADER_ACTIONS_MIN_WIDTH
 
   // Utilitários: ícone no desktop, item de menu no celular. Três ícones lado a lado em 375px não
   // caberiam com área de toque decente, e nenhum deles é a ação principal do atendimento.
-  const utilities = [
+  const utilityCandidates: readonly (ResolvedUtility | undefined)[] = [
     onOpenDocuments
-      ? { key: 'documents', icon: '📄', label: labels.documents, run: onOpenDocuments, active: documentsOpen }
+      ? {
+          key: 'documents',
+          icon: <FileText size={ICON_SIZE_ACTION} />,
+          label: labels.documents,
+          run: onOpenDocuments,
+          active: documentsOpen,
+        }
+      : undefined,
+    onDownload
+      ? {
+          key: 'download',
+          icon: <Download size={ICON_SIZE_ACTION} />,
+          label: labels.download,
+          run: onDownload,
+          active: false,
+        }
       : undefined,
-    onDownload ? { key: 'download', icon: '⬇️', label: labels.download, run: onDownload, active: false } : undefined,
     ...(extraUtilities ?? []).map((utility) => ({ ...utility, active: utility.active ?? false })),
-  ].filter(
-    (utility): utility is { key: string; icon: string; label: string; run: () => void; active: boolean } =>
-      Boolean(utility),
-  )
+  ]
+  const utilities = utilityCandidates.filter((utility): utility is ResolvedUtility => Boolean(utility))
 
   // Lista única de ações: alimenta os botões do desktop e o menu do celular, para as duas
   // superfícies nunca divergirem sobre o que está disponível.
-  const actions = [
+  // `hint` existe separado do `label` porque o host pode traduzir o rótulo com prefixo ou contagem:
+  // no tooltip isso vira ruído, e é o texto limpo que descreve a ação.
+  const actionCandidates: readonly (HeaderAction | undefined)[] = [
     !isHuman && onTakeover
-      ? { key: 'takeover', label: labels.takeover, run: onTakeover, className: 'cv-header-action--primary' }
+      ? {
+          key: 'takeover',
+          icon: <Headset size={ICON_SIZE_ACTION} />,
+          label: labels.takeover,
+          hint: labels.takeover,
+          run: onTakeover,
+          className: 'cv-header-action--primary',
+        }
+      : undefined,
+    isHuman && onReturnToBot
+      ? {
+          key: 'release',
+          icon: <Bot size={ICON_SIZE_ACTION} />,
+          label: labels.returnToBot,
+          hint: labels.returnToBot,
+          run: onReturnToBot,
+          className: '',
+        }
       : undefined,
-    isHuman && onReturnToBot ? { key: 'release', label: labels.returnToBot, run: onReturnToBot, className: '' } : undefined,
     isHuman && onFinish
-      ? { key: 'finish', label: `✕ ${labels.finish}`, run: onFinish, className: 'cv-header-action--danger' }
+      ? {
+          key: 'finish',
+          icon: <X size={ICON_SIZE_ACTION} />,
+          label: labels.finish,
+          hint: labels.finish,
+          run: onFinish,
+          className: 'cv-header-action--danger',
+        }
       : undefined,
-  ].filter((action): action is { key: string; label: string; run: () => void; className: string } => Boolean(action))
+  ]
+  const actions = actionCandidates.filter((action): action is HeaderAction => Boolean(action))
 
-  // No celular utilitários e ações moram no mesmo menu: utilitários primeiro, porque são consulta e
-  // não alteram estado da conversa.
+  // O menu recebe só o que não coube na faixa: utilitários primeiro, porque são consulta e não
+  // alteram estado da conversa. Nada aparece nos dois lugares — item duplicado é o operador achando
+  // que são duas coisas diferentes.
   const menuItems = [
-    ...utilities.map((utility) => ({
-      key: utility.key,
-      label: `${utility.icon} ${utility.label}`,
-      run: utility.run,
-      className: '',
-    })),
-    ...actions,
+    ...(showsUtilitiesInline
+      ? []
+      : utilities.map((utility) => ({
+          key: utility.key,
+          icon: utility.icon,
+          label: utility.label,
+          hint: utility.label,
+          run: utility.run,
+          className: '',
+        }))),
+    ...(showsActionsInline ? [] : actions),
   ]
 
   // `flex-nowrap` no cabeçalho: com wrap, o nome do cliente ocupava a largura toda em 375px e
@@ -148,6 +228,7 @@ export function ConversationHeader({
   // fora da tela. O bloco de identificação encurta (truncate) em vez de empurrar.
   return (
     <header
+      ref={headerRef}
       className={cn(
         'flex flex-nowrap items-center justify-between gap-3 border-b px-4 py-3',
         classNames?.root,
@@ -158,76 +239,93 @@ export function ConversationHeader({
         {/* Voltar existe só em tela estreita, onde lista e conversa não cabem juntas: sem ele, abrir
             uma conversa no celular é um beco sem saída. A classe some acima de 1024px. */}
         {onBack ? (
-          <button type="button" onClick={onBack} className="cv-back cv-touch" aria-label={labels.back} title={labels.back}>
-            ←
+          <button type="button" onClick={onBack} className="cv-back cv-touch" aria-label={labels.back} data-cv-tooltip={labels.back}>
+            <ArrowLeft size={ICON_SIZE_ACTION} aria-hidden="true" />
           </button>
         ) : null}
         {/* Sem nome, o Avatar cai na silhueta — melhor que dois dígitos do telefone como iniciais. */}
         <Avatar name={conversation.clientName} size="md" />
         <div className="min-w-0">
           <p className={cn('truncate font-medium', classNames?.name)}>{conversation.clientName ?? displayHandle}</p>
-          <p className={cn('truncate text-xs text-gray-500', classNames?.meta)}>
+          {/* Flex com `items-center`, não texto corrido: ícone de canal e emoji de modo têm altura
+              maior que a fonte, e como elementos inline cada um assentava na própria baseline —
+              telefone, canal e modo saíam em três alturas diferentes. O gap substitui as margens. */}
+          <p className={cn('flex min-w-0 flex-nowrap items-center gap-2 overflow-hidden text-xs text-gray-500', classNames?.meta)}>
             {/* Bandeira derivada do DDI e só quando o identificador é telefone. Estava fixa em 🇧🇷,
                 o que rotulava qualquer contato como brasileiro. */}
-            {flag ? `${flag} ` : ''}
-            {displayHandle}
-            {/* Em tela estreita sobra o ícone do canal e o emoji do modo: o rótulo escrito empurra o
+            <span className="truncate">
+              {flag ? `${flag} ` : ''}
+              {displayHandle}
+            </span>
+            {/* Em faixa estreita sobra só o ícone do canal e o do modo: o rótulo escrito empurra o
                 telefone para fora e não diz nada que o ícone já não diga. */}
-            <span className="ml-2 inline-flex items-center gap-1">
+            <span className="inline-flex flex-shrink-0 items-center gap-1">
               <ChannelIcon channel={conversation.channel} />
-              <span className="cv-only-wide">{capabilities.label}</span>
+              {showsUtilitiesInline ? <span>{capabilities.label}</span> : null}
             </span>
-            <span className="ml-2 cv-only-wide">{isHuman ? labels.humanMode : labels.botMode}</span>
-            <span className="ml-1 cv-only-narrow" title={isHuman ? labels.humanMode : labels.botMode}>
-              {isHuman ? '🧑‍💼' : '🤖'}
+            <span
+              className="inline-flex flex-shrink-0 items-center gap-1"
+              // Sem o rótulo escrito, o ícone sozinho não diria nada ao leitor de tela.
+              {...(showsUtilitiesInline
+                ? {}
+                : { role: 'img', 'aria-label': isHuman ? labels.humanMode : labels.botMode, 'data-cv-tooltip': isHuman ? labels.humanMode : labels.botMode })}
+            >
+              {isHuman ? (
+                <UserRound size={ICON_SIZE_INLINE} aria-hidden="true" />
+              ) : (
+                <Bot size={ICON_SIZE_INLINE} aria-hidden="true" />
+              )}
+              {showsUtilitiesInline ? <span>{isHuman ? labels.humanMode : labels.botMode}</span> : null}
             </span>
           </p>
         </div>
       </div>
 
       <div className={cn('flex shrink-0 items-center gap-2', classNames?.actions)}>
-        {/* Desktop: utilitários como ícone e ações como botão, tudo visível de uma vez. */}
-        <div className={cn('hidden items-center gap-2 lg:flex', classNames?.desktopActions)}>
-          {utilities.map((utility) => (
+        {/* Faixa larga: utilitários como ícone e ações como botão, tudo visível de uma vez. */}
+        <div className={cn('flex items-center gap-2', classNames?.desktopActions)}>
+          {(showsUtilitiesInline ? utilities : []).map((utility) => (
             <button
               key={utility.key}
               type="button"
               onClick={utility.run}
               disabled={busy}
               aria-pressed={utility.active}
-              title={utility.label}
+              data-cv-tooltip={utility.label}
               aria-label={utility.label}
               className={`cv-header-icon ${utility.active ? 'cv-header-icon--active' : ''}`}
             >
               {utility.icon}
             </button>
           ))}
-          {actions.map((action) => (
+          {(showsActionsInline ? actions : []).map((action) => (
             <button
               key={action.key}
               type="button"
               onClick={action.run}
               disabled={busy}
+              data-cv-tooltip={action.hint} aria-label={action.hint}
               className={`cv-header-action ${action.className}`}
             >
+              {action.icon}
               {action.label}
             </button>
           ))}
         </div>
 
-        {/* Celular: um único ⋮ com tudo dentro. Três ícones de 30px lado a lado violavam o mínimo
-            de 44px de área de toque e disputavam espaço com o nome do cliente. */}
+        {/* Faixa estreita: um único ⋮ com o que não coube. Ícones de 30px lado a lado violavam o
+            mínimo de 44px de área de toque e disputavam espaço com o nome do cliente. */}
         {menuItems.length > 0 ? (
-          <div className={cn('cv-menu lg:hidden', classNames?.mobileMenu)}>
+          <div className={cn('cv-menu', classNames?.mobileMenu)}>
             <button
               type="button"
               onClick={() => setMenuOpen(!menuOpen)}
               aria-expanded={menuOpen}
               aria-label={labels.moreActions}
-              title={labels.moreActions}
+              data-cv-tooltip={labels.moreActions}
               className="cv-header-icon cv-touch"
             >
-              ⋮
+              <MoreVertical size={ICON_SIZE_ACTION} aria-hidden="true" />
             </button>
 
             {menuOpen ? (
@@ -242,8 +340,10 @@ export function ConversationHeader({
                       item.run()
                     }}
                     disabled={busy}
+                    data-cv-tooltip={item.hint} aria-label={item.hint}
                     className={`cv-header-action cv-touch ${item.className}`}
                   >
+                    {item.icon}
                     {item.label}
                   </button>
                 ))}

package/src/ConversationListItem.tsx

@@ -128,6 +128,7 @@ export const ConversationListItem = ({
 
   return (
     <button
+      data-cv-tooltip={name} aria-label={name}
       onClick={handleClick}
       className={`w-full flex items-center gap-3 px-3 py-2.5 text-left transition-colors ${highlightActive ? "hover:bg-[#f0f2f5]" : ""} ${showDivider ? "border-b border-[#e9edef]" : ""}`}
       style={{
@@ -150,10 +151,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={expiredWindowLabel} />
+              <span className="w-2 h-2 rounded-full bg-red-500 flex-shrink-0" data-cv-tooltip={expiredWindowLabel} />
             )}
             {windowStatus && windowStatus.label === 'warning' && (
-              <span className="w-2 h-2 rounded-full bg-orange-500 flex-shrink-0" title={warningWindowLabel} />
+              <span className="w-2 h-2 rounded-full bg-orange-500 flex-shrink-0" data-cv-tooltip={warningWindowLabel} />
             )}
           </div>
           {timestamp && (

package/src/ConversationRow.tsx

@@ -7,8 +7,11 @@
  * como se opera uma fila de atendimento no WhatsApp.
  */
 
+import { AlarmClock, Bot, Hourglass, Play, UserRound } from 'lucide-react'
+
 import { ConversationListItem } from './ConversationListItem'
 import { capabilitiesOf } from './conversationChannel'
+import { ICON_SIZE_ACTION, ICON_SIZE_PILL } from './icon.constant'
 import { cn } from './lib/cn'
 import { ChannelIcon } from './ChannelIcon'
 import type { ConversationSummary } from './providers/types'
@@ -31,6 +34,8 @@ const WINDOW_TITLE: Record<ConversationWindow, string> = {
 // Abaixo disto a conversa é recente e o aviso de "parada" só faria ruído.
 const STALLED_THRESHOLD_MS = 60 * 60 * 1000
 
+const TAKEOVER_LABEL = 'Continuar Atendimento'
+
 const WINDOW_BAR_CLASS: Record<ConversationWindow, string> = {
   [CONVERSATION_WINDOW.ALL]: 'bg-transparent',
   [CONVERSATION_WINDOW.FRESH]: 'bg-green-500',
@@ -85,7 +90,7 @@ export function ConversationRow({
           duplica as bolinhas que o próprio ConversationListItem já desenha. */}
       <span
         className={cn('w-1 shrink-0', WINDOW_BAR_CLASS[window], classNames?.windowBar)}
-        title={WINDOW_TITLE[window]}
+        data-cv-tooltip={WINDOW_TITLE[window]}
         aria-label={WINDOW_TITLE[window]}
       />
 
@@ -118,16 +123,35 @@ export function ConversationRow({
             <ChannelIcon channel={conversation.channel} /> {capabilities.label}
           </span>
           {conversation.mode === 'human' ? (
-            <span className="cv-pill cv-pill--success">🧑‍💼 em atendimento</span>
+            <span className="cv-pill cv-pill--success">
+              <UserRound size={ICON_SIZE_PILL} aria-hidden="true" /> em atendimento
+            </span>
+          ) : null}
+          {isWaiting ? (
+            <span className="cv-pill cv-pill--warning">
+              <Hourglass size={ICON_SIZE_PILL} aria-hidden="true" /> aguardando atendimento
+            </span>
+          ) : null}
+          {!isWaiting && conversation.mode === 'bot' ? (
+            <span className="cv-pill">
+              <Bot size={ICON_SIZE_PILL} aria-hidden="true" /> bot ativo
+            </span>
           ) : null}
-          {isWaiting ? <span className="cv-pill cv-pill--warning">⏳ aguardando atendimento</span> : null}
-          {!isWaiting && conversation.mode === 'bot' ? <span className="cv-pill">🤖 bot ativo</span> : null}
           {isStalled ? (
-            <span className="cv-pill cv-pill--danger">⏱️ parada há {formatStalledFor(conversation.lastAt, now)}</span>
+            <span className="cv-pill cv-pill--danger">
+              <AlarmClock size={ICON_SIZE_PILL} aria-hidden="true" /> parada há{' '}
+              {formatStalledFor(conversation.lastAt, now)}
+            </span>
           ) : null}
           {isWaiting ? (
-            <button type="button" onClick={onTakeover} disabled={busy} className="cv-header-action">
-              ▶️ Continuar Atendimento
+            <button
+              type="button"
+              onClick={onTakeover}
+              disabled={busy}
+              data-cv-tooltip={TAKEOVER_LABEL} aria-label={TAKEOVER_LABEL}
+              className="cv-header-action"
+            >
+              <Play size={ICON_SIZE_ACTION} aria-hidden="true" /> {TAKEOVER_LABEL}
             </button>
           ) : null}
         </div>

package/src/DocumentsLibrary.tsx

@@ -13,6 +13,7 @@ import { useConversations } from './providers/ConversationsProvider'
 import { DOCUMENT_SOURCE_FILTER, type DocumentSourceFilter } from './ConversationDocumentsPanel'
 import { FileIcon } from './FileIcon'
 import { cn } from './lib/cn'
+import { PAGINATION_LABELS } from './pagination.constant'
 import { formatDateTime, formatFileSize } from './lib/format'
 import { formatPhone } from './lib/phone'
 import type { CompanyDocument } from './providers/types'
@@ -181,6 +182,7 @@ export function DocumentsLibrary({
         </select>
 
         <button
+          data-cv-tooltip={sortDirection === 'desc' ? labels.sortMostRecent : labels.sortOldest} aria-label={sortDirection === 'desc' ? labels.sortMostRecent : labels.sortOldest}
           type="button"
           onClick={() => applyFilter(() => setSortDirection(sortDirection === 'desc' ? 'asc' : 'desc'))}
           className={cn('cv-header-action inline-flex items-center gap-1', classNames?.sortButton)}
@@ -191,6 +193,7 @@ export function DocumentsLibrary({
 
         {hasFilters ? (
           <button
+            data-cv-tooltip={labels.clearFilters} aria-label={labels.clearFilters}
             type="button"
             onClick={() =>
               applyFilter(() => {
@@ -234,7 +237,7 @@ export function DocumentsLibrary({
               <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}>
+                  <div className={cn('truncate text-sm font-medium', classNames?.filename)} data-cv-tooltip={document.filename}>
                     {document.filename}
                   </div>
                   <div className={cn('flex flex-wrap items-center gap-x-2 text-xs text-gray-500', classNames?.meta)}>
@@ -256,7 +259,7 @@ export function DocumentsLibrary({
                 <button
                   type="button"
                   onClick={() => onOpenConversation(document.conversationId)}
-                  title={labels.openConversation}
+                  data-cv-tooltip={labels.openConversation} aria-label={labels.openConversation}
                   className={cn('cv-header-action inline-flex shrink-0 items-center gap-1', classNames?.conversationLink)}
                 >
                   <MessageSquare size={12} />
@@ -272,7 +275,7 @@ export function DocumentsLibrary({
                 <button
                   type="button"
                   onClick={() => void handleOpen(document.id, 'inline')}
-                  title={labels.view}
+                  data-cv-tooltip={labels.view}
                   aria-label={`${labels.view}: ${document.filename}`}
                   className="cv-header-icon"
                 >
@@ -281,7 +284,7 @@ export function DocumentsLibrary({
                 <button
                   type="button"
                   onClick={() => void handleOpen(document.id, 'attachment')}
-                  title={labels.download}
+                  data-cv-tooltip={labels.download}
                   aria-label={`${labels.download}: ${document.filename}`}
                   className="cv-header-icon"
                 >
@@ -298,6 +301,7 @@ export function DocumentsLibrary({
           <span className="text-gray-400">{labels.total(total)}</span>
           <div className="flex items-center gap-2">
             <button
+              data-cv-tooltip={PAGINATION_LABELS.previous} aria-label={PAGINATION_LABELS.previous}
               type="button"
               onClick={() => setPage(page - 1)}
               disabled={page <= 1}
@@ -307,6 +311,7 @@ export function DocumentsLibrary({
             </button>
             <span className="text-gray-500">{labels.page(page, lastPage)}</span>
             <button
+              data-cv-tooltip={PAGINATION_LABELS.next} aria-label={PAGINATION_LABELS.next}
               type="button"
               onClick={() => setPage(page + 1)}
               disabled={page >= lastPage}

package/src/EmojiPicker.tsx

@@ -55,6 +55,7 @@ export const EmojiPicker = ({ onSelect, labels, className = '' }: EmojiPickerPro
         <div className="flex border-b border-gray-200 overflow-x-auto">
           {EMOJI_CATEGORIES.map((category, index) => (
             <button
+              data-cv-tooltip={category.name} aria-label={category.name}
               key={category.name}
               onClick={() => setActiveCategory(index)}
               className={`px-3 py-2 text-xs font-medium whitespace-nowrap border-b-2 transition-colors ${
@@ -79,7 +80,7 @@ export const EmojiPicker = ({ onSelect, labels, className = '' }: EmojiPickerPro
               onClick={() => handleSelect(entry.emoji)}
               className="w-8 h-8 flex items-center justify-center text-lg hover:bg-gray-100 rounded transition-colors cursor-pointer"
               aria-label={entry.emoji}
-              title={entry.keywords[0]}
+              data-cv-tooltip={entry.keywords[0]}
             >
               {entry.emoji}
             </button>

package/src/InteractiveMessage.tsx

@@ -86,6 +86,7 @@ export function InteractiveMessage({ payload, onSelect, labels, className }: Int
         <div className="mt-1 flex flex-col gap-1 border-t border-gray-200 pt-1 dark:border-gray-700">
           {buttons.map((button) => (
             <button
+              data-cv-tooltip={button.title} aria-label={button.title}
               key={button.id}
               type="button"
               disabled={!isInteractable}
@@ -101,6 +102,7 @@ export function InteractiveMessage({ payload, onSelect, labels, className }: Int
       {hasRows ? (
         <div className="mt-1 border-t border-gray-200 pt-1 dark:border-gray-700">
           <button
+            data-cv-tooltip={payload.action?.button ?? openListLabel} aria-label={payload.action?.button ?? openListLabel}
             type="button"
             onClick={() => setIsListOpen((open) => !open)}
             aria-expanded={isListOpen}
@@ -120,6 +122,7 @@ export function InteractiveMessage({ payload, onSelect, labels, className }: Int
                   ) : null}
                   {(section.rows ?? []).map((row) => (
                     <button
+                      data-cv-tooltip={row.title} aria-label={row.title}
                       key={row.id}
                       type="button"
                       disabled={!isInteractable}

package/src/Lightbox.tsx

@@ -25,7 +25,7 @@ export function Lightbox({ imageUrl, caption, onClose, labels }: LightboxProps)
       <div className="max-w-[90vw] max-h-[90vh] flex flex-col items-center" onClick={(e) => e.stopPropagation()}>
         <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">{closeLabel}</button>
+        <button data-cv-tooltip={closeLabel} aria-label={closeLabel} 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

@@ -106,6 +106,7 @@ export function MediaRenderer({
   function LazyMediaButton({ icon, label }: { icon: ReactNode; label: string }) {
     return (
       <button
+        data-cv-tooltip={label} aria-label={label}
         onClick={lazy.load}
         disabled={lazy.loading}
         className="flex min-w-[180px] items-center gap-2 rounded-lg bg-black/5 px-2 py-1.5 text-left transition-colors hover:bg-black/10 disabled:opacity-60 dark:bg-white/10 dark:hover:bg-white/15"
@@ -214,6 +215,7 @@ export function MediaRenderer({
             </a>
           ) : canLazyLoad ? (
             <button
+              data-cv-tooltip={bubble.downloadFile}
               onClick={lazy.load}
               disabled={lazy.loading}
               className="w-8 h-8 flex items-center justify-center rounded-full bg-gray-200 hover:bg-gray-300 flex-shrink-0 transition-colors disabled:opacity-50"

package/src/MessageBubble.test.tsx

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { MessageBubble } from './MessageBubble'
+import type { MessagePayload } from './types'
+
+const IMAGE_MESSAGE: MessagePayload = {
+  id: 'msg-1',
+  type: 'image',
+  direction: 'outbound',
+  sender: 'agent',
+  timestamp: '2026-08-05T12:00:00.000Z',
+  filename: 'planta-baixa.png',
+  mediaUrl: 'https://cdn.test/planta-baixa.png',
+}
+
+describe('MessageBubble com mídia', () => {
+  it('mostra a legenda que veio no conteúdo do envio', () => {
+    const markup = renderToStaticMarkup(
+      <MessageBubble message={{ ...IMAGE_MESSAGE, content: 'Planta do 302' }} isMine />,
+    )
+
+    expect(markup).toContain('Planta do 302')
+  })
+
+  it('mostra a legenda que o cliente mandou junto da imagem', () => {
+    const markup = renderToStaticMarkup(
+      <MessageBubble message={{ ...IMAGE_MESSAGE, direction: 'inbound', sender: 'customer', caption: 'É esse?' }} isMine={false} />,
+    )
+
+    expect(markup).toContain('É esse?')
+  })
+
+  it('não repete o nome do arquivo como se fosse legenda', () => {
+    const markup = renderToStaticMarkup(
+      <MessageBubble message={{ ...IMAGE_MESSAGE, content: 'planta-baixa.png' }} isMine />,
+    )
+
+    expect(markup).not.toContain('>planta-baixa.png<')
+  })
+})