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

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>

package/src/WhatsAppMessageEditor.tsx

@@ -1,7 +1,29 @@
 import { useRef, type ReactNode } from 'react'
 import { Bold, Italic, Strikethrough } from 'lucide-react'
 
+export interface WhatsAppMessageEditorLabels {
+  bold: string
+  /** Tooltip da negrito — traz a sintaxe do WhatsApp junto, por isso é separado do `aria-label`. */
+  boldHint: string
+  italic: string
+  italicHint: string
+  strikethrough: string
+  strikethroughHint: string
+  insertPlaceholder: (token: string) => string
+}
+
+export const DEFAULT_WHATSAPP_MESSAGE_EDITOR_LABELS: WhatsAppMessageEditorLabels = {
+  bold: 'Negrito',
+  boldHint: 'Negrito (*texto*)',
+  italic: 'Itálico',
+  italicHint: 'Itálico (_texto_)',
+  strikethrough: 'Tachado',
+  strikethroughHint: 'Tachado (~texto~)',
+  insertPlaceholder: (token: string) => `Inserir ${token}`,
+}
+
 export interface WhatsAppMessageEditorProps {
+  labels?: Partial<WhatsAppMessageEditorLabels>
   value: string
   onChange: (value: string) => void
   placeholder?: string
@@ -56,7 +78,9 @@ export function WhatsAppMessageEditor({
   rows = 4,
   previewLabel = 'Prévia (como aparece no WhatsApp)',
   emptyPreviewText = 'Sua mensagem aparecerá aqui…',
+  labels,
 }: WhatsAppMessageEditorProps) {
+  const editorLabels = { ...DEFAULT_WHATSAPP_MESSAGE_EDITOR_LABELS, ...labels }
   const textareaRef = useRef<HTMLTextAreaElement>(null)
 
   function wrapSelection(marker: string): void {
@@ -93,13 +117,13 @@ export function WhatsAppMessageEditor({
   return (
     <div>
       <div className="flex flex-wrap items-center gap-1.5 mb-2">
-        <button type="button" onClick={() => wrapSelection('*')} className={toolbarButtonClass} title="Negrito (*texto*)" aria-label="Negrito">
+        <button type="button" onClick={() => wrapSelection('*')} className={toolbarButtonClass} title={editorLabels.boldHint} aria-label={editorLabels.bold}>
           <Bold size={15} />
         </button>
-        <button type="button" onClick={() => wrapSelection('_')} className={toolbarButtonClass} title="Itálico (_texto_)" aria-label="Itálico">
+        <button type="button" onClick={() => wrapSelection('_')} className={toolbarButtonClass} title={editorLabels.italicHint} aria-label={editorLabels.italic}>
           <Italic size={15} />
         </button>
-        <button type="button" onClick={() => wrapSelection('~')} className={toolbarButtonClass} title="Tachado (~texto~)" aria-label="Tachado">
+        <button type="button" onClick={() => wrapSelection('~')} className={toolbarButtonClass} title={editorLabels.strikethroughHint} aria-label={editorLabels.strikethrough}>
           <Strikethrough size={15} />
         </button>
         {placeholders.length > 0 && (
@@ -111,7 +135,7 @@ export function WhatsAppMessageEditor({
                 type="button"
                 onClick={() => insertAtCursor(token)}
                 className="inline-flex items-center h-8 px-2 rounded-lg border border-gray-200 dark:border-gray-600 text-xs text-blue-600 dark:text-blue-300 hover:bg-blue-50 dark:hover:bg-blue-900/40 transition-colors"
-                title={`Inserir ${token}`}
+                title={editorLabels.insertPlaceholder(token)}
               >
                 {token}
               </button>

package/src/hooks/useConversationActions.ts

@@ -0,0 +1,56 @@
+import { useMemo } from 'react'
+import { useConversations } from '../providers/ConversationsProvider'
+import type { ConversationTemplate } from '../providers/types'
+
+export interface UseConversationActionsResult {
+  /** `undefined` quando a API do host não implementa a operação — a UI esconde a afordância. */
+  takeover: (() => Promise<void>) | undefined
+  release: (() => Promise<void>) | undefined
+  finalize: (() => Promise<void>) | undefined
+}
+
+/**
+ * Ações de atendimento de UMA conversa, já ligadas ao id.
+ *
+ * Separado de `useConversationMessages` porque assumir e devolver conversa também acontece a
+ * partir da lista, onde nenhuma thread está aberta — embutir nas mensagens obrigaria a carregar
+ * a thread inteira só para desenhar um botão na linha.
+ */
+export function useConversationActions(conversationId: string): UseConversationActionsResult {
+  const context = useConversations()
+  if (!context) {
+    throw new Error('useConversationActions requires an ancestor <ConversationsProvider>')
+  }
+  const { api } = context
+
+  return useMemo(
+    () => ({
+      takeover: api.takeover ? () => api.takeover!(conversationId) : undefined,
+      release: api.release ? () => api.release!(conversationId) : undefined,
+      finalize: api.finalize ? () => api.finalize!(conversationId) : undefined,
+    }),
+    [api, conversationId],
+  )
+}
+
+export interface UseInboxActionsResult {
+  markAllRead: (() => Promise<void>) | undefined
+  listTemplates: (() => Promise<ConversationTemplate[]>) | undefined
+}
+
+/** Ações que valem para a caixa inteira, sem conversa selecionada. */
+export function useInboxActions(): UseInboxActionsResult {
+  const context = useConversations()
+  if (!context) {
+    throw new Error('useInboxActions requires an ancestor <ConversationsProvider>')
+  }
+  const { api } = context
+
+  return useMemo(
+    () => ({
+      markAllRead: api.markAllRead ? () => api.markAllRead!() : undefined,
+      listTemplates: api.listTemplates ? () => api.listTemplates!() : undefined,
+    }),
+    [api],
+  )
+}

package/src/hooks/useConversationDocuments.ts

@@ -1,14 +1,14 @@
 import { useConversations } from '../providers/ConversationsProvider'
 import { useAsyncResource } from './useAsyncResource'
-import type { ConversationDocument } from '../providers/types'
+import { documentsOf, totalOf } from '../lib/paginated'
+import type { ConversationDocument, ListDocumentsParams } from '../providers/types'
 
-export interface UseConversationDocumentsParams {
-  search?: string
-  page?: number
-}
+export type UseConversationDocumentsParams = ListDocumentsParams
 
 export interface UseConversationDocumentsResult {
   documents: ConversationDocument[]
+  /** Total no servidor. Cai para o tamanho da página quando a API devolve só o array. */
+  total: number
   loading: boolean
   error: Error | undefined
   refetch: () => Promise<void>
@@ -28,8 +28,12 @@ export function useConversationDocuments(
 
   const { data, loading, error, refetch } = useAsyncResource(
     () => (conversationId ? api.getDocuments(conversationId, params) : Promise.resolve([])),
-    [conversationId, params?.search, params?.page],
+    [conversationId, params?.search, params?.page, params?.limit, params?.source, params?.sortDirection],
   )
 
-  return { documents: data ?? [], loading, error, refetch }
+  if (data === undefined) {
+    return { documents: [], total: 0, loading, error, refetch }
+  }
+
+  return { documents: documentsOf(data), total: totalOf(data), loading, error, refetch }
 }

package/src/hooks/useConversationList.ts

@@ -1,16 +1,14 @@
 import { useConversations } from '../providers/ConversationsProvider'
 import { useAsyncResource } from './useAsyncResource'
-import type { ConversationSummary } from '../providers/types'
+import { conversationsOf, totalOf } from '../lib/paginated'
+import type { ConversationSummary, ListConversationsParams } from '../providers/types'
 
-export interface UseConversationListParams {
-  page?: number
-  limit?: number
-  waitingHuman?: boolean
-  search?: string
-}
+export type UseConversationListParams = ListConversationsParams
 
 export interface UseConversationListResult {
   conversations: ConversationSummary[]
+  /** Total no servidor. Cai para o tamanho da página quando a API devolve só o array. */
+  total: number
   loading: boolean
   error: Error | undefined
   refetch: () => Promise<void>
@@ -23,10 +21,18 @@ export function useConversationList(params?: UseConversationListParams): UseConv
   }
   const { api } = context
 
+  // `filters` é objeto novo a cada render do host; serializar evita refetch em laço sem obrigar
+  // o consumidor a memoizar — omissão que só apareceria como loop de rede em produção.
+  const filtersKey = JSON.stringify(params?.filters ?? {})
+
   const { data, loading, error, refetch } = useAsyncResource(
     () => api.fetchConversations(params),
-    [params?.page, params?.limit, params?.waitingHuman, params?.search],
+    [params?.page, params?.limit, params?.waitingHuman, params?.search, filtersKey],
   )
 
-  return { conversations: data ?? [], loading, error, refetch }
+  if (data === undefined) {
+    return { conversations: [], total: 0, loading, error, refetch }
+  }
+
+  return { conversations: conversationsOf(data), total: totalOf(data), loading, error, refetch }
 }

package/src/hooks/useConversationMessages.ts

@@ -10,7 +10,7 @@ export interface UseConversationMessagesResult {
   refetch: () => Promise<void>
   sendMessage: (text: string) => Promise<MessagePayload>
   sendMedia: (data: { base64: string; mimeType: string; filename: string; caption?: string }) => Promise<MessagePayload>
-  sendTemplate: (data: { templateName: string; languageCode?: string; bodyParams?: string[] }) => Promise<void>
+  sendTemplate: (data: { templateName?: string; languageCode?: string; bodyParams?: string[] }) => Promise<void>
   markRead: () => Promise<void>
 }
 
@@ -51,7 +51,7 @@ export function useConversationMessages(
   )
 
   const sendTemplate = useCallback(
-    async (templateData: { templateName: string; languageCode?: string; bodyParams?: string[] }) => {
+    async (templateData: { templateName?: string; languageCode?: string; bodyParams?: string[] }) => {
       await api.sendTemplate(conversationId, templateData)
       await refetch()
     },

package/src/index.ts

@@ -3,16 +3,16 @@ export { ConversationWallpaper } from './Wallpaper'
 export { ConversationLocalesProvider, useConversationLocales } from './ConversationLocalesProvider'
 export { AudioPlayer } from './AudioPlayer'
 export { EmojiPicker } from './EmojiPicker'
-export { MessageComposer } from './MessageComposer'
-export { WhatsAppMessageEditor } from './WhatsAppMessageEditor'
+export { MessageComposer, DEFAULT_MESSAGE_COMPOSER_LABELS } from './MessageComposer'
+export { WhatsAppMessageEditor, DEFAULT_WHATSAPP_MESSAGE_EDITOR_LABELS } from './WhatsAppMessageEditor'
 export { SimpleEmojiPicker } from './SimpleEmojiPicker'
 export { DateDivider } from './DateDivider'
-export { Avatar } from './Avatar'
-export { ConversationListItem } from './ConversationListItem'
+export { Avatar, DEFAULT_AVATAR_LABELS } from './Avatar'
+export { ConversationListItem, DEFAULT_CONVERSATION_LIST_ITEM_LABELS } from './ConversationListItem'
 export { ToastProvider, useToast, toast } from './Toast'
 
 export { StatusTicks } from './StatusTicks'
-export { Lightbox } from './Lightbox'
+export { Lightbox, DEFAULT_LIGHTBOX_LABELS } from './Lightbox'
 export { MediaRenderer } from './MediaRenderer'
 export { FileIcon } from './FileIcon'
 export { MessageText } from './MessageText'
@@ -65,6 +65,10 @@ export type {
 } from './ConversationContextPanel'
 export { WindowExpiredNotice, isWindowBlocking, DEFAULT_WINDOW_EXPIRED_LABELS } from './WindowExpiredNotice'
 export type { WindowExpiredNoticeProps, WindowExpiredNoticeLabels } from './WindowExpiredNotice'
+export { DocumentsLibrary, DEFAULT_DOCUMENTS_LIBRARY_LABELS } from './DocumentsLibrary'
+export type { DocumentsLibraryProps, DocumentsLibraryLabels, DocumentsLibraryClassNames } from './DocumentsLibrary'
+export { DOCUMENT_SOURCE_FILTER } from './ConversationDocumentsPanel'
+export type { DocumentSourceFilter } from './ConversationDocumentsPanel'
 export type { ConversationDocumentsPanelClassNames } from './ConversationDocumentsPanel'
 export { ConversationDocumentsPanel, DEFAULT_CONVERSATION_DOCUMENTS_LABELS } from './ConversationDocumentsPanel'
 export type { ConversationDocumentsPanelProps, ConversationDocumentsPanelLabels } from './ConversationDocumentsPanel'
@@ -74,6 +78,11 @@ export type { BuildTranscriptTextParams } from './conversationTranscript'
 export { useDarkMode, useIsDarkTheme } from './useDarkMode'
 export { useIsNarrow, NARROW_MAX_WIDTH_PX } from './useIsNarrow'
 export { useWaitingNotifications } from './useWaitingNotifications'
+export type {
+  UseWaitingNotificationsLabels,
+  UseWaitingNotificationsParams,
+  UseWaitingNotificationsResult,
+} from './useWaitingNotifications'
 
 export { ConversationsProvider, useConversations } from './providers/ConversationsProvider'
 
@@ -96,10 +105,13 @@ export { useConversationList } from './hooks/useConversationList'
 export { useConversationContext } from './hooks/useConversationContext'
 export { useConversationDocuments } from './hooks/useConversationDocuments'
 export { useConversationRealtime, useGlobalRealtime } from './hooks/useConversationRealtime'
+export { useConversationActions, useInboxActions } from './hooks/useConversationActions'
 
 export { parseWhatsAppFormatting, waToHTML, htmlToWA, waToHTMLInline } from './lib/whatsapp-formatting'
 export { formatPhone, phoneInitials } from './lib/phone'
-export { formatTimestamp, formatFileSize } from './lib/format'
+// `formatDateTime` e `isSameDay` já eram usados pelas bolhas e pelo divisor de data; exportá-los
+// evita que cada host mantenha a própria cópia e acabe com timeline e transcript divergindo.
+export { formatTimestamp, formatFileSize, formatDateTime, isSameDay } from './lib/format'
 
 export type { MessagePayload, ConversationsUIConfig, ConversationsTheme, ConversationsFeatures } from './types'
 export type {
@@ -108,21 +120,29 @@ export type {
   ConversationEventSource,
   ConversationSummary,
   ConversationDocument,
+  ConversationPage,
+  ConversationDocumentPage,
+  CompanyDocument,
+  CompanyDocumentPage,
+  ConversationTemplate,
+  ListConversationsParams,
+  ListDocumentsParams,
 } from './providers/types'
+export type { UseConversationActionsResult, UseInboxActionsResult } from './hooks/useConversationActions'
 
 export type { MessageBubbleProps } from './MessageBubble'
 export type { ConversationWallpaperProps } from './Wallpaper'
 export type { ConversationLocales, ConversationLocalesProviderProps } from './ConversationLocalesProvider'
 export type { AudioPlayerProps } from './AudioPlayer'
 export type { EmojiPickerProps } from './EmojiPicker'
-export type { MessageComposerProps, MessageComposerClassNames } from './MessageComposer'
-export type { WhatsAppMessageEditorProps } from './WhatsAppMessageEditor'
+export type { MessageComposerProps, MessageComposerClassNames, MessageComposerLabels } from './MessageComposer'
+export type { WhatsAppMessageEditorProps, WhatsAppMessageEditorLabels } from './WhatsAppMessageEditor'
 export type { SimpleEmojiPickerProps } from './SimpleEmojiPicker'
 export type { DateDividerProps, DateDividerClassNames } from './DateDivider'
-export type { AvatarProps } from './Avatar'
-export type { ConversationListItemProps } from './ConversationListItem'
+export type { AvatarProps, AvatarLabels } from './Avatar'
+export type { ConversationListItemProps, ConversationListItemLabels } from './ConversationListItem'
 export type { StatusTicksProps } from './StatusTicks'
-export type { LightboxProps } from './Lightbox'
+export type { LightboxProps, LightboxLabels } from './Lightbox'
 export type { MediaRendererProps, ResolveMediaUrl } from './MediaRenderer'
 export type { FileIconProps } from './FileIcon'
 export type { MessageTextProps } from './MessageText'
@@ -154,3 +174,4 @@ export type { UseConversationContextResult } from './hooks/useConversationContex
 export type { UseConversationDocumentsParams, UseConversationDocumentsResult } from './hooks/useConversationDocuments'
 export type { ConversationRealtimeHandler } from './hooks/useConversationRealtime'
 export type { AsyncResourceState } from './hooks/useAsyncResource'
+export { createMediaUrlResolver } from './lib/createMediaUrlResolver'

package/src/lib/cn.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'bun:test'
+
+import { cn } from './cn'
+
+describe('cn', () => {
+  // O contrato de `classNames`/`className` dos componentes depende disto: se o override não vencer,
+  // a API de customização é decorativa. Concatenar falharia justo no caso comum — o Tailwind emite
+  // `px-2` antes de `px-4`, então a base ganharia de quem quer apertar o espaçamento.
+  it('o override do host vence a classe base em conflito', () => {
+    expect(cn('px-4 py-3', 'px-2')).toBe('py-3 px-2')
+  })
+
+  it('mantém o que não conflita', () => {
+    expect(cn('flex items-center gap-3', 'gap-1')).toBe('flex items-center gap-1')
+  })
+
+  it('preserva classes próprias do pacote, que o merge não conhece', () => {
+    expect(cn('cv-row flex', 'bg-red-50')).toBe('cv-row flex bg-red-50')
+  })
+
+  it('ignora ausente, falso e vazio', () => {
+    expect(cn('border-b', undefined, false, '')).toBe('border-b')
+  })
+
+  it('aplica condicional na ordem recebida', () => {
+    const isCompact = false
+    expect(cn('mt-2', isCompact && 'mt-8', 'mt-4')).toBe('mt-4')
+  })
+})

package/src/lib/createMediaUrlResolver.ts

@@ -0,0 +1,33 @@
+/**
+ * Resolve a mídia de uma mensagem numa URL exibível, usando só o `ConversationsApi`.
+ *
+ * Mora no pacote, e não em cada host, porque a regra não tem nada de específico de produto: é a
+ * tradução de `uploadId`/`mediaId` pelos dois métodos que o próprio contrato já declara. Deixá-la no
+ * host significava que todo projeto que adotasse o SDK reescreveria as mesmas oito linhas — e, na
+ * prática, ninguém escrevia: o `MediaRenderer` só busca mídia pela porta `onResolveMediaUrl`, então
+ * onde nada era injetado foto, vídeo e áudio ficavam no placeholder para sempre.
+ */
+
+import type { MessagePayload } from '../types'
+import type { ConversationsApi } from '../providers/types'
+import type { ResolveMediaUrl } from '../MediaRenderer'
+
+export function createMediaUrlResolver(
+  api: Pick<ConversationsApi, 'getDocumentUrl' | 'getMediaProxyUrl'>,
+): ResolveMediaUrl {
+  return async (message: MessagePayload): Promise<string | null> => {
+    // Mídia já copiada para o storage do host: sai por URL assinada e o binário não passa pela API.
+    // `inline` porque aqui o arquivo é para VER na tela — `attachment` faria o navegador baixar.
+    if (message.uploadId) return api.getDocumentUrl(message.uploadId, 'inline')
+
+    // Antes da ingestão só existe o id na Meta, cuja URL expira; o backend busca e devolve base64.
+    // Data URL serve de `src` para `<img>`/`<video>`/`<audio>`: o bloqueio do Chrome a `data:` vale
+    // para navegação de topo, não para carregar mídia dentro da página.
+    if (message.mediaId) {
+      const { mimeType, data } = await api.getMediaProxyUrl(message.mediaId)
+      return `data:${mimeType};base64,${data}`
+    }
+
+    return null
+  }
+}

package/src/lib/paginated.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'bun:test'
+import { conversationsOf, documentsOf, totalOf } from './paginated'
+import type { ConversationDocument, ConversationSummary } from '../providers/types'
+
+const conversation = { id: '1', whatsappNumber: '5511900000000' } as ConversationSummary
+const document = { id: 'd1', filename: 'contrato.pdf' } as ConversationDocument
+
+describe('normalização de lista ou página', () => {
+  // As duas formas existem porque o contrato aceita as duas: array puro é o retorno original, e
+  // implementações antigas continuam válidas. Um consumidor que só tratasse uma delas quebraria
+  // em runtime, não no compilador.
+  it('aceita o array puro do contrato original', () => {
+    expect(conversationsOf([conversation])).toEqual([conversation])
+    expect(documentsOf([document])).toEqual([document])
+  })
+
+  it('desembrulha a forma paginada', () => {
+    expect(conversationsOf({ conversations: [conversation], total: 42 })).toEqual([conversation])
+    expect(documentsOf({ documents: [document], total: 7 })).toEqual([document])
+  })
+
+  it('usa o total do servidor quando ele vem, e o tamanho da página quando não vem', () => {
+    // A distinção importa: com array puro não dá para saber se a página é a última, então o
+    // melhor palpite honesto é o que se tem em mãos.
+    expect(totalOf({ conversations: [conversation], total: 42 })).toBe(42)
+    expect(totalOf([conversation])).toBe(1)
+  })
+
+  it('trata página vazia sem confundir com ausência de dados', () => {
+    expect(conversationsOf({ conversations: [], total: 0 })).toEqual([])
+    expect(totalOf({ conversations: [], total: 0 })).toBe(0)
+  })
+})

package/src/lib/paginated.ts

@@ -0,0 +1,26 @@
+import type {
+  ConversationDocument,
+  ConversationDocumentPage,
+  ConversationPage,
+  ConversationSummary,
+} from '../providers/types'
+
+/**
+ * `fetchConversations` e `getDocuments` devolvem o array puro (contrato original) ou uma página
+ * com total. Normalizar num lugar só evita que cada consumidor invente sua própria checagem —
+ * e um consumidor esquecido não falha no compilador, falha em runtime com `.map is not a
+ * function`.
+ */
+export function conversationsOf(result: ConversationSummary[] | ConversationPage): ConversationSummary[] {
+  return Array.isArray(result) ? result : result.conversations
+}
+
+export function documentsOf(result: ConversationDocument[] | ConversationDocumentPage): ConversationDocument[] {
+  return Array.isArray(result) ? result : result.documents
+}
+
+export function totalOf(
+  result: ConversationSummary[] | ConversationPage | ConversationDocument[] | ConversationDocumentPage,
+): number {
+  return Array.isArray(result) ? result.length : result.total
+}

package/src/preview/MediaTypesPreview.tsx

@@ -0,0 +1,87 @@
+/**
+ * Bancada de teste manual de mídia — montável em uma linha por qualquer projeto que adote o SDK.
+ *
+ * Existe porque o defeito que ela pega não é pegável por teste automatizado: "o PDF abre?" depende
+ * do leitor do navegador, "o vídeo toca?" do decodificador, e "a aba abre?" da política do Chrome
+ * sobre `data:` URL. Teste unitário confere bytes; só o olho confere que o arquivo abre. Sem uma
+ * superfície pronta no pacote, cada projeto teria de montar a sua — e, na prática, nenhum montava.
+ *
+ * Traz o próprio store, o próprio mock e o próprio provider: o host não injeta nada. E não passa
+ * `onResolveMediaUrl` em lugar nenhum de propósito — é o `MessageBubble` resolvendo mídia pelo
+ * `ConversationsApi` do contexto, então se essa resolução automática quebrar, esta tela mostra.
+ */
+
+import { useMemo } from 'react'
+import { ConversationsProvider } from '../providers/ConversationsProvider'
+import { DocumentsLibrary } from '../DocumentsLibrary'
+import { ConversationDocumentsPanel } from '../ConversationDocumentsPanel'
+import { MessageBubble } from '../MessageBubble'
+import { ConversationWallpaper } from '../Wallpaper'
+import { createMockConversationsApi } from './createMockConversationsApi'
+import { createMockSSEProvider } from './createMockSSEProvider'
+import { createPreviewStore } from './previewStore'
+import { PREVIEW_CONVERSATIONS, PREVIEW_DOCUMENTS, PREVIEW_MESSAGES } from './previewFixtures'
+
+/** A conversa do fixture que carrega uma mensagem de cada tipo aceito. */
+export const MEDIA_TYPES_CONVERSATION_ID = '5511944443333'
+
+export type MediaTypesPreviewProps = {
+  /** Outra conversa do fixture, se o projeto tiver acrescentado a sua. */
+  conversationId?: string
+  className?: string
+}
+
+export function MediaTypesPreview({
+  conversationId = MEDIA_TYPES_CONVERSATION_ID,
+  className,
+}: MediaTypesPreviewProps) {
+  const store = useMemo(
+    () => createPreviewStore({ conversations: PREVIEW_CONVERSATIONS, messages: PREVIEW_MESSAGES }),
+    [],
+  )
+  const api = useMemo(() => createMockConversationsApi({ store }), [store])
+  const sse = useMemo(() => createMockSSEProvider({ store }), [store])
+
+  const messages = PREVIEW_MESSAGES[conversationId] ?? []
+  const documents = PREVIEW_DOCUMENTS[conversationId] ?? []
+  const mimeTypes = [...new Set(documents.map((document) => document.mimeType))]
+
+  return (
+    <ConversationsProvider api={api} sse={sse}>
+      <div className={className}>
+        <header className="border-b px-4 py-3 dark:border-gray-700">
+          <h1 className="text-lg font-semibold">Teste manual de mídia</h1>
+          <p className="text-sm text-gray-500">
+            {documents.length} arquivos, {mimeTypes.length} tipos. Clique no olho para abrir em aba nova e no
+            botão da bolha para carregar a mídia na thread — é o que teste automatizado não vê.
+          </p>
+        </header>
+
+        <div className="grid gap-4 p-4 lg:grid-cols-2">
+          <section className="space-y-3">
+            <h2 className="text-sm font-semibold uppercase tracking-wide text-gray-500">Biblioteca da empresa</h2>
+            {/* Sem paginar: a bancada serve para ver TODOS os tipos de uma vez. */}
+            <DocumentsLibrary perPage={documents.length || 20} />
+          </section>
+
+          <section className="space-y-3">
+            <h2 className="text-sm font-semibold uppercase tracking-wide text-gray-500">Painel da conversa</h2>
+            <ConversationDocumentsPanel conversationId={conversationId} open perPage={documents.length || 20} />
+
+            <h2 className="text-sm font-semibold uppercase tracking-wide text-gray-500">Bolhas na thread</h2>
+            <ConversationWallpaper className="max-h-[70vh] overflow-y-auto rounded-lg px-3 py-2">
+              {messages.map((message, index) => (
+                <MessageBubble
+                  key={message.id}
+                  message={message}
+                  isMine={message.direction === 'outbound'}
+                  isFirstInGroup={index === 0 || messages[index - 1]?.sender !== message.sender}
+                />
+              ))}
+            </ConversationWallpaper>
+          </section>
+        </div>
+      </div>
+    </ConversationsProvider>
+  )
+}