@adatechnology/conversations-ui 0.13.0 → 0.14.0

package/src/participant/participantLabels.ts

@@ -44,6 +44,29 @@ export type ParticipantConversationsLabels = {
   readonly edit: string
   /** Name of the menu button on a failed message. Optional; translated hosts should fill it, otherwise the English default shows. */
   readonly messageOptions?: string
+  /** Message menu (opt-in `messageMenu`). Optional; translated hosts should fill them, otherwise English shows. */
+  readonly copyMessage?: string
+  readonly copySelection?: string
+  readonly selectMessages?: string
+  /** Name of the check box beside each message in selection mode. */
+  readonly selectMessage?: string
+  readonly cancelSelection?: string
+  /** Selection bar count; `{count}` is replaced. */
+  readonly selectedCount?: string
+  /** Message info panel: when it was sent, its delivery state and when it was read. */
+  readonly messageInfo?: string
+  readonly infoAuthor?: string
+  readonly infoSentAt?: string
+  readonly infoStatus?: string
+  readonly infoReadAt?: string
+  readonly closeMessageInfo?: string
+  /** Header menu of a thread with `messageMenu`: select messages and download the conversation as text. */
+  readonly conversationOptions?: string
+  readonly downloadConversation?: string
+  /** Transcribed audio: the word before what was said in copies and exports, and its two menu entries. */
+  readonly transcriptionPrefix?: string
+  readonly copyTranscription?: string
+  readonly downloadTranscription?: string
   /** Toggle that opens the message as received (e.g. the whole email). Optional; the English default shows otherwise. */
   readonly showOriginalText?: string
   readonly notFound: string
@@ -110,6 +133,23 @@ export const DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS: ParticipantConversationsL
   edit: 'Edit',
   messageOptions: DEFAULT_MESSAGE_OPTIONS_LABEL,
   showOriginalText: DEFAULT_SHOW_ORIGINAL_TEXT_LABEL,
+  copyMessage: 'Copy',
+  copySelection: 'Copy selection',
+  selectMessages: 'Select messages',
+  selectMessage: 'Select message',
+  cancelSelection: 'Cancel selection',
+  selectedCount: '{count} selected',
+  messageInfo: 'Message info',
+  infoAuthor: 'From',
+  infoSentAt: 'Sent',
+  infoStatus: 'Status',
+  infoReadAt: 'Read',
+  closeMessageInfo: 'Close',
+  conversationOptions: 'Conversation options',
+  downloadConversation: 'Download conversation',
+  transcriptionPrefix: 'Transcription',
+  copyTranscription: 'Copy transcription',
+  downloadTranscription: 'Download transcription',
   notFound: 'Conversation not found',
   loading: 'Loading…',
   loadError: 'Could not load. Check your connection and try again.',

package/src/participant/participantMessageInfoModel.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'bun:test'
+
+import type { ParticipantMessageActionsTarget } from './ParticipantAuthorAvatar'
+import { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS as LABELS } from './participantLabels'
+import { conversationExportFileName, conversationExportText, messageInfoRows } from './participantMessageInfoModel'
+
+function target(overrides: Partial<ParticipantMessageActionsTarget>): ParticipantMessageActionsTarget {
+  return {
+    id: 'm1',
+    text: 'Hello',
+    authorName: 'Bruno',
+    isMine: false,
+    attachments: [],
+    createdAt: '2026-10-01T13:05:00.000Z',
+    ...overrides,
+  }
+}
+
+describe('message info', () => {
+  it('lists author and send time of an incoming message, and nothing about delivery', () => {
+    const rows = messageInfoRows(target({ status: 'read', readAt: '2026-10-01T14:00:00.000Z' }), LABELS, 'pt-BR')
+    expect(rows.map((row) => row.id)).toEqual(['author', 'sent'])
+    expect(rows[0]?.value).toBe('Bruno')
+    expect(rows[1]?.value).toMatch(/^01\/10\/2026 \d{2}:05$/)
+  })
+
+  it('adds delivery state and read time to a message this side sent', () => {
+    const rows = messageInfoRows(
+      target({ isMine: true, status: 'read', readAt: '2026-10-01T14:10:00.000Z' }),
+      LABELS,
+      'pt-BR',
+    )
+    expect(rows.map((row) => [row.id, row.label])).toEqual([
+      ['author', 'From'],
+      ['sent', 'Sent'],
+      ['status', 'Status'],
+      ['read', 'Read'],
+    ])
+    expect(rows[0]?.value).toBe(LABELS.me)
+    expect(rows[2]?.value).toBe(LABELS.statusRead)
+    expect(rows[3]?.value).toMatch(/:10$/)
+  })
+
+  it('leaves out what the channel never reported', () => {
+    expect(messageInfoRows(target({ isMine: true }), LABELS).map((row) => row.id)).toEqual(['author', 'sent'])
+  })
+})
+
+describe('conversation export', () => {
+  it('writes the title, a blank line and one stamped line per message', () => {
+    const text = conversationExportText({
+      title: 'Order 12',
+      messages: [target({}), target({ id: 'm2', isMine: true, text: 'Ok' })],
+      locale: 'pt-BR',
+      meLabel: 'Me',
+    })
+    const lines = text.split('\n')
+    expect(lines[0]).toBe('Order 12')
+    expect(lines[1]).toBe('')
+    expect(lines[2]).toMatch(/^\[01\/10\/2026 \d{2}:05\] Bruno: Hello$/)
+    expect(lines[3]).toMatch(/\] Me: Ok$/)
+  })
+
+  it('makes a safe file name from the title', () => {
+    expect(conversationExportFileName('NF 123/1: atraso')).toBe('NF 123 1 atraso.txt')
+    expect(conversationExportFileName('  //  ')).toBe('conversation.txt')
+  })
+})

package/src/participant/participantMessageInfoModel.ts

@@ -0,0 +1,80 @@
+import type { MessageDeliveryStatus } from '@adatechnology/conversation-contracts'
+
+import type { ParticipantMessageActionsTarget } from './ParticipantAuthorAvatar'
+import {
+  DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS as DEFAULTS,
+  type ParticipantConversationsLabels,
+} from './participantLabels'
+import { formatMessagesForCopy } from './participantMessageMenuModel'
+import { formatMessageMoment } from './participantMessageMoment'
+
+export type ParticipantMessageInfoRow = { readonly id: string; readonly label: string; readonly value: string }
+
+function statusLabel(status: MessageDeliveryStatus, labels: ParticipantConversationsLabels): string {
+  const byStatus: Record<MessageDeliveryStatus, string> = {
+    queued: labels.statusQueued,
+    sent: labels.statusSent,
+    delivered: labels.statusDelivered,
+    read: labels.statusRead,
+    failed: labels.statusFailedShort,
+    bounced: labels.statusFailedShort,
+  }
+  return byStatus[status]
+}
+
+/**
+ * What the info panel lists: who wrote it and when; for a message this side sent, also how far it got and
+ * when it was read, as far as the channel told. Nothing is invented: an unknown step is left out.
+ */
+export function messageInfoRows(
+  message: ParticipantMessageActionsTarget,
+  labels: ParticipantConversationsLabels,
+  locale?: string,
+): readonly ParticipantMessageInfoRow[] {
+  const author = message.isMine ? labels.me : (message.authorName ?? '')
+  const rows: ParticipantMessageInfoRow[] = []
+  if (author !== '') rows.push({ id: 'author', label: labels.infoAuthor ?? DEFAULTS.infoAuthor ?? '', value: author })
+  rows.push({
+    id: 'sent',
+    label: labels.infoSentAt ?? DEFAULTS.infoSentAt ?? '',
+    value: formatMessageMoment(message.createdAt, locale),
+  })
+  if (!message.isMine) return rows
+  if (message.status) {
+    rows.push({
+      id: 'status',
+      label: labels.infoStatus ?? DEFAULTS.infoStatus ?? '',
+      value: statusLabel(message.status, labels),
+    })
+  }
+  if (message.readAt) {
+    rows.push({
+      id: 'read',
+      label: labels.infoReadAt ?? DEFAULTS.infoReadAt ?? '',
+      value: formatMessageMoment(message.readAt, locale),
+    })
+  }
+  return rows
+}
+
+type ConversationExport = {
+  readonly title: string
+  readonly messages: readonly ParticipantMessageActionsTarget[]
+  readonly locale?: string
+  readonly meLabel: string
+  readonly transcriptionLabel?: string
+}
+
+/** The conversation as a text file: the title, a blank line, then one `[date time] author: text` line each. */
+export function conversationExportText({ title, messages, ...format }: ConversationExport): string {
+  return `${title}\n\n${formatMessagesForCopy(messages, format)}\n`
+}
+
+/** A file name any system accepts, from the conversation title. */
+export function conversationExportFileName(title: string): string {
+  const safe = title
+    .replace(/[\\/:*?"<>|]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+  return `${safe === '' ? 'conversation' : safe}.txt`
+}

package/src/participant/participantMessageMenuDom.test.tsx

@@ -0,0 +1,111 @@
+import { afterAll, beforeAll, describe, expect, it } from 'bun:test'
+import { act } from 'react'
+
+import { setupDom, pressKey, type DomHarness } from '../domHarness.test-helper'
+import { ParticipantMessageMenuProvider } from './ParticipantMessageMenuContext'
+import { ParticipantSelectionBar } from './ParticipantSelectionBar'
+import { ParticipantTimeline } from './ParticipantTimeline'
+import { buildMessage } from './participantFixtures.test-helper'
+import { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS as LABELS } from './participantLabels'
+import type { ParticipantMessageMenuOptions } from './participantMessageMenuModel'
+import type { ParticipantTimelineItem } from './participantMessages'
+import { useParticipantMessageMenu } from './ParticipantMessageMenuContext'
+
+let harness: DomHarness
+
+beforeAll(async () => {
+  harness = await setupDom()
+})
+afterAll(() => harness.teardown())
+
+const ITEMS: readonly ParticipantTimelineItem[] = [
+  { kind: 'server', message: buildMessage({ id: 'm1', text: 'First', direction: 'inbound', authorName: 'Bruno' }) },
+  { kind: 'server', message: buildMessage({ id: 'm2', text: 'Second', direction: 'inbound', authorName: 'Bruno' }) },
+]
+
+function Bar() {
+  const menu = useParticipantMessageMenu()
+  return menu?.isSelecting ? <ParticipantSelectionBar state={menu} /> : null
+}
+
+function mount(options?: ParticipantMessageMenuOptions) {
+  return harness.mount(
+    <ParticipantMessageMenuProvider options={options} labels={LABELS} items={ITEMS}>
+      <div className="cv-p-thread__scroll">
+        <ParticipantTimeline items={ITEMS} labels={LABELS} resolveAttachmentUrl={() => Promise.resolve('')} />
+      </div>
+      <Bar />
+    </ParticipantMessageMenuProvider>,
+  )
+}
+
+function fire(element: Element, type: string): void {
+  act(() => element.dispatchEvent(new MouseEvent(type, { bubbles: true, cancelable: true })))
+}
+
+function menuLabels(container: HTMLElement): string[] {
+  return Array.from(container.querySelectorAll('[role="menuitem"]')).map((item) => item.textContent ?? '')
+}
+
+describe('message menu in a DOM', () => {
+  it('draws nothing new when the host did not opt in', () => {
+    const { container, unmount } = mount()
+    expect(container.querySelector('.cv-p-message-menu')).toBeNull()
+    unmount()
+  })
+
+  it('opens from the chevron with Copy, Select messages and the host entries', () => {
+    const forward = { id: 'forward', label: 'Forward', onSelect: () => undefined }
+    const { container, unmount } = mount({ items: () => [forward] })
+    const trigger = container.querySelector<HTMLButtonElement>('.cv-p-message-menu__trigger')!
+    expect(trigger.getAttribute('aria-haspopup')).toBe('menu')
+    fire(trigger, 'click')
+    expect(menuLabels(container)).toEqual(['Copy', 'Select messages', 'Message info', 'Forward'])
+    unmount()
+  })
+
+  it('opens from a right-click on the bubble', () => {
+    const { container, unmount } = mount({})
+    fire(container.querySelector('.cv-p-bubble')!, 'contextmenu')
+    expect(menuLabels(container)).toEqual(['Copy', 'Select messages', 'Message info'])
+    unmount()
+  })
+
+  it('selects messages with a check box per row, a bar with the count, and Escape leaves', () => {
+    let received: readonly string[] = []
+    const { container, unmount } = mount({
+      selectionActions: () => [
+        { id: 'fw', label: 'Forward all', onSelect: (messages) => (received = messages.map((m) => m.id)) },
+      ],
+    })
+    fire(container.querySelectorAll('.cv-p-message-menu__trigger')[1]!, 'click')
+    fire(
+      Array.from(container.querySelectorAll('[role="menuitem"]')).find(
+        (item) => item.textContent === 'Select messages',
+      )!,
+      'click',
+    )
+    expect(container.querySelectorAll('.cv-p-select-row').length).toBe(2)
+    expect(container.querySelector('.cv-p-selection-bar__count')?.textContent).toBe('1 selected')
+    fire(container.querySelectorAll('.cv-p-select-row')[0]!, 'click')
+    expect(container.querySelector('.cv-p-selection-bar__count')?.textContent).toBe('2 selected')
+    fire(
+      Array.from(container.querySelectorAll('.cv-p-selection-bar__action')).find(
+        (b) => b.textContent === 'Forward all',
+      )!,
+      'click',
+    )
+    expect(received).toEqual(['m1', 'm2'])
+    expect(container.querySelector('.cv-p-selection-bar')).toBeNull()
+    fire(container.querySelector('.cv-p-message-menu__trigger')!, 'click')
+    fire(
+      Array.from(container.querySelectorAll('[role="menuitem"]')).find(
+        (item) => item.textContent === 'Select messages',
+      )!,
+      'click',
+    )
+    pressKey(document.body, 'Escape')
+    expect(container.querySelector('.cv-p-select-row')).toBeNull()
+    unmount()
+  })
+})

package/src/participant/participantMessageMenuModel.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'bun:test'
+
+import type { ParticipantMessageActionsTarget } from './ParticipantAuthorAvatar'
+import { copyableText, formatMessagesForCopy, selectedInOrder, toggleSelectedId } from './participantMessageMenuModel'
+
+const FIRST: ParticipantMessageActionsTarget = {
+  id: 'm1',
+  text: 'Wait at the dock.',
+  authorName: 'Ana',
+  isMine: true,
+  attachments: [],
+  createdAt: '2026-10-20T14:20:00',
+}
+const SECOND: ParticipantMessageActionsTarget = {
+  id: 'm2',
+  text: '  Here is the bill.  ',
+  authorName: 'Bruno',
+  isMine: false,
+  attachments: [{ id: 'a1', kind: 'document', filename: 'bill.pdf', mimeType: 'application/pdf', sizeBytes: 10 }],
+  createdAt: '2026-10-20T14:41:00',
+}
+
+describe('message menu model', () => {
+  it('toggles an id in and out, keeping the pick order', () => {
+    expect(toggleSelectedId(['m2'], 'm1')).toEqual(['m2', 'm1'])
+    expect(toggleSelectedId(['m2', 'm1'], 'm2')).toEqual(['m1'])
+  })
+
+  it('returns the selection in conversation order, not pick order', () => {
+    expect(selectedInOrder([FIRST, SECOND], ['m2', 'm1']).map((message) => message.id)).toEqual(['m1', 'm2'])
+  })
+
+  it('copies one message as its trimmed text, and nothing for a file alone', () => {
+    expect(copyableText(SECOND)).toBe('Here is the bill.')
+    expect(copyableText({ text: '   ' })).toBeNull()
+  })
+
+  it('copies several messages with date, time and author, one line each, files by name', () => {
+    expect(formatMessagesForCopy([FIRST, SECOND], { locale: 'pt-BR', meLabel: 'Eu' })).toBe(
+      '[20/10/2026 14:20] Eu: Wait at the dock.\n[20/10/2026 14:41] Bruno: Here is the bill. [bill.pdf]',
+    )
+  })
+})

package/src/participant/participantMessageMenuModel.ts

@@ -0,0 +1,91 @@
+import type { ParticipantMessageActionsTarget } from './ParticipantAuthorAvatar'
+import { formatMessageMoment } from './participantMessageMoment'
+import { attachmentForCopy } from './participantTranscriptionText'
+
+/** One entry the host adds to a message's menu, after the package's own (copy, select). */
+export type ParticipantMessageMenuItem = {
+  readonly id: string
+  readonly label: string
+  /** Runs on choice; the menu closes first. */
+  readonly onSelect?: () => void
+  /** Draws the entry as a link (a file to open or save) instead of a button. */
+  readonly href?: string
+  /** With `href`: the file name the browser saves it under. */
+  readonly download?: string
+  readonly disabled?: boolean
+}
+
+/** One button the host adds to the selection bar; it receives the selected messages in conversation order. */
+export type ParticipantSelectionAction = {
+  readonly id: string
+  readonly label: string
+  readonly onSelect: (messages: readonly ParticipantMessageActionsTarget[]) => void
+  readonly disabled?: boolean
+}
+
+/**
+ * Opt-in message menu, as in common chat apps: a discreet chevron on the bubble (or a right-click, or a long
+ * press) opens Copy and Select messages, plus the host's entries. Absent leaves the bubble as it was.
+ */
+export type ParticipantMessageMenuOptions = {
+  readonly items?: (message: ParticipantMessageActionsTarget) => readonly ParticipantMessageMenuItem[]
+  readonly selectionActions?: (
+    messages: readonly ParticipantMessageActionsTarget[],
+  ) => readonly ParticipantSelectionAction[]
+}
+
+/** Adds the id, or removes it when it is already there; keeps the rest in the order they were picked. */
+export function toggleSelectedId(ids: readonly string[], id: string): readonly string[] {
+  return ids.includes(id) ? ids.filter((candidate) => candidate !== id) : [...ids, id]
+}
+
+/** The selected messages in the order of the conversation, whatever order they were picked in. */
+export function selectedInOrder(
+  messages: readonly ParticipantMessageActionsTarget[],
+  ids: readonly string[],
+): readonly ParticipantMessageActionsTarget[] {
+  const picked = new Set(ids)
+  return messages.filter((message) => picked.has(message.id))
+}
+
+/** The trimmed text of one message, or null when there is nothing to copy (a file alone). */
+export function copyableText(message: Pick<ParticipantMessageActionsTarget, 'text'>): string | null {
+  const text = message.text?.trim() ?? ''
+  return text === '' ? null : text
+}
+
+type CopyFormat = {
+  readonly locale?: string
+  readonly meLabel: string
+  /** Precedes what was said in a transcribed audio. */
+  readonly transcriptionLabel?: string
+}
+
+/**
+ * Several messages as text: one line each, `[date time] author: text [file]`, like a chat export. A transcribed
+ * audio carries what was said, so the text stands on its own outside the thread.
+ */
+export function formatMessagesForCopy(
+  messages: readonly ParticipantMessageActionsTarget[],
+  format: CopyFormat,
+): string {
+  return messages
+    .map((message) => {
+      const author = message.isMine ? format.meLabel : (message.authorName ?? '')
+      const head = `[${formatMessageMoment(message.createdAt, format.locale)}]${author === '' ? '' : ` ${author}:`}`
+      const files = message.attachments.map((attachment) =>
+        attachmentForCopy(attachment, format.transcriptionLabel ?? 'Transcription'),
+      )
+      return [head, copyableText(message) ?? '', ...files].filter((part) => part !== '').join(' ')
+    })
+    .join('\n')
+}
+
+/** Text the user selected, when it starts and ends inside the element; empty otherwise. */
+export function selectedTextWithin(container: Element | null): string {
+  const selection = typeof window === 'undefined' ? null : window.getSelection()
+  if (!container || !selection || selection.isCollapsed) return ''
+  const { anchorNode, focusNode } = selection
+  if (!anchorNode || !focusNode || !container.contains(anchorNode) || !container.contains(focusNode)) return ''
+  return selection.toString().trim()
+}

package/src/participant/participantMessageMoment.ts

@@ -0,0 +1,7 @@
+/** Date and time in the reader's locale, as the copy, the export and the info panel write them. */
+export function formatMessageMoment(iso: string, locale?: string): string {
+  const date = new Date(iso)
+  const day = date.toLocaleDateString(locale, { day: '2-digit', month: '2-digit', year: 'numeric' })
+  const time = date.toLocaleTimeString(locale, { hour: '2-digit', minute: '2-digit' })
+  return `${day} ${time}`
+}

package/src/participant/participantTranscriptionText.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'bun:test'
+
+import type { ParticipantAttachment } from '@adatechnology/conversation-contracts'
+
+import type { ParticipantMessageActionsTarget } from './ParticipantAuthorAvatar'
+import { formatMessagesForCopy } from './participantMessageMenuModel'
+import { readyTranscriptions, transcriptionFileName } from './participantTranscriptionText'
+
+const READY = { status: 'ready', text: '  Cheguei na doca.  ', generatedAt: '2026-10-01T13:06:00.000Z' } as const
+
+function audio(overrides: Partial<ParticipantAttachment> = {}): ParticipantAttachment {
+  return {
+    id: 'a1',
+    kind: 'audio',
+    filename: 'voz.ogg',
+    mimeType: 'audio/ogg',
+    sizeBytes: 10,
+    transcription: READY,
+    ...overrides,
+  }
+}
+
+describe('transcription text', () => {
+  it('keeps only ready, non-empty transcriptions of audios', () => {
+    expect(readyTranscriptions([audio()])).toEqual([{ filename: 'voz.ogg', text: 'Cheguei na doca.' }])
+    expect(readyTranscriptions([audio({ transcription: { status: 'pending' } })])).toEqual([])
+    expect(readyTranscriptions([audio({ transcription: { ...READY, text: ' ' } })])).toEqual([])
+    expect(readyTranscriptions([audio({ kind: 'document', filename: 'a.pdf' })])).toEqual([])
+  })
+
+  it('puts what was said in copies and exports, after the file name', () => {
+    const message: ParticipantMessageActionsTarget = {
+      id: 'm1',
+      text: null,
+      authorName: 'Bruno',
+      isMine: false,
+      attachments: [audio()],
+      createdAt: '2026-10-01T13:05:00.000Z',
+    }
+    expect(
+      formatMessagesForCopy([message], { locale: 'pt-BR', meLabel: 'Eu', transcriptionLabel: 'Transcrição' }),
+    ).toMatch(/^\[01\/10\/2026 \d{2}:05\] Bruno: \[voz\.ogg\] Transcrição: Cheguei na doca\.$/)
+  })
+
+  it('names the file after the audio', () => {
+    expect(transcriptionFileName('audio-motorista.ogg', 'Transcrição')).toBe('audio-motorista Transcrição.txt')
+  })
+})

package/src/participant/participantTranscriptionText.ts

@@ -0,0 +1,28 @@
+import type { ParticipantAttachment } from '@adatechnology/conversation-contracts'
+
+export type ReadyTranscription = { readonly filename: string; readonly text: string }
+
+/** The audios of a message whose transcription is ready and says something, in attachment order. */
+export function readyTranscriptions(attachments: readonly ParticipantAttachment[]): readonly ReadyTranscription[] {
+  return attachments.flatMap((attachment) => {
+    const transcription = attachment.kind === 'audio' ? attachment.transcription : undefined
+    const text = transcription?.status === 'ready' ? transcription.text.trim() : ''
+    return text === '' ? [] : [{ filename: attachment.filename, text }]
+  })
+}
+
+/** One attachment in a copy or an export: `[file]`, followed by what was said when the audio was transcribed. */
+export function attachmentForCopy(attachment: ParticipantAttachment, transcriptionLabel: string): string {
+  const [ready] = readyTranscriptions([attachment])
+  return ready ? `[${attachment.filename}] ${transcriptionLabel}: ${ready.text}` : `[${attachment.filename}]`
+}
+
+/** The file name of one audio's transcription: the audio's name without its extension, then the label. */
+export function transcriptionFileName(audioFilename: string, transcriptionLabel: string): string {
+  const base = audioFilename.replace(/\.[^.]+$/, '')
+  const safe = `${base} ${transcriptionLabel}`
+    .replace(/[\\/:*?"<>|]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+  return `${safe}.txt`
+}

package/src/participant/useOpenUpwards.ts

@@ -0,0 +1,22 @@
+import { useLayoutEffect, useState, type RefObject } from 'react'
+
+const SCROLLER_SELECTOR = '.cv-p-thread__scroll'
+
+/**
+ * A panel under a bubble opens downwards; when that would cross the bottom of the thread's scrolling area (the
+ * last messages), it opens upwards instead, so it is never cut off.
+ */
+export function useOpenUpwards(isOpen: boolean, panelRef: RefObject<HTMLElement | null>): boolean {
+  const [isUpwards, setUpwards] = useState(false)
+  useLayoutEffect(() => {
+    const panel = panelRef.current
+    if (!isOpen || !panel) {
+      setUpwards(false)
+      return
+    }
+    const scroller = panel.closest(SCROLLER_SELECTOR)
+    if (!scroller) return
+    setUpwards(panel.getBoundingClientRect().bottom > scroller.getBoundingClientRect().bottom)
+  }, [isOpen, panelRef])
+  return isUpwards
+}

package/src/participant/useParticipantFailedMenu.ts

@@ -21,6 +21,8 @@ export type ParticipantFailedMenuController = {
   readonly handleMenuKeyDown: (event: KeyboardEvent<HTMLDivElement>) => void
   readonly handleBlur: (event: FocusEvent<HTMLSpanElement>) => void
   readonly close: () => void
+  /** Opens with the first item focused, as a right-click or a long press does. */
+  readonly open: () => void
 }
 
 export function useParticipantFailedMenu(): ParticipantFailedMenuController {
@@ -56,5 +58,6 @@ export function useParticipantFailedMenu(): ParticipantFailedMenuController {
     handleMenuKeyDown: (event) => handleFailedMenuKeyDown({ event, menuRef, triggerRef, dispatch }),
     handleBlur,
     close: () => dispatch({ type: 'close' }),
+    open: () => dispatch({ type: 'open', initialFocus: 'first' }),
   }
 }

package/src/styles.css

@@ -1328,6 +1328,45 @@
 .cv-p-failed-menu__list--below { bottom: auto; top: calc(100% + 0.25rem); }
 .cv-p-failed-menu__item--danger { color: var(--cv-p-i-danger); }
 .cv-p-failed-menu__item:hover, .cv-p-failed-menu__item:focus-visible { background: var(--cv-p-i-highlight); }
+/* Menu da mensagem (opt-in `messageMenu`): seta discreta no canto do balão, à vista só com o ponteiro em cima, com
+   foco ou com o menu aberto; no toque abre por toque longo e a seta não ocupa o balão. */
+.cv-p-message-menu { position: absolute; top: 0.2rem; right: 0.2rem; display: inline-flex; }
+.cv-p-message-menu__trigger { display: inline-grid; place-items: center; width: 1.5rem; height: 1.25rem; padding: 0; border: 0; border-radius: var(--cv-p-i-radius); color: var(--cv-p-i-text-muted); background: var(--cv-p-tail-fill, var(--cv-p-i-surface-raised)); box-shadow: -0.5rem 0 0.5rem var(--cv-p-tail-fill, var(--cv-p-i-surface-raised)); cursor: pointer; opacity: 0; }
+.cv-p-bubble:hover .cv-p-message-menu__trigger, .cv-p-message-menu__trigger:focus-visible, .cv-p-message-menu[data-open] .cv-p-message-menu__trigger { opacity: 1; }
+.cv-p-message-menu__trigger:hover { color: var(--cv-p-i-text); }
+@media (hover: none) { .cv-p-message-menu__trigger:not(:focus-visible) { pointer-events: none; } }
+.cv-p-message-menu__list { min-width: 11rem; }
+.cv-p-message-menu__list { bottom: auto; top: calc(100% + 0.25rem); }
+.cv-p-message-menu__list.cv-p-message-menu__list--up { top: auto; bottom: calc(100% + 0.25rem); }
+.cv-p-message-menu__item { display: flex; align-items: center; font: inherit; font-size: 0.85rem; text-transform: none; letter-spacing: normal; text-decoration: none; white-space: nowrap; }
+.cv-p-message-menu__item:disabled, .cv-p-message-menu__item[aria-disabled='true'] { color: var(--cv-p-i-text-muted); cursor: default; }
+.cv-p-bubble--menu-open { z-index: 3; }
+.cv-p-bubble:has(.cv-p-message-menu[data-open]) { z-index: 3; }
+.cv-p-conversation-menu { position: relative; display: inline-flex; }
+.cv-p-conversation-menu__trigger { display: inline-flex; align-items: center; justify-content: center; min-width: var(--cv-p-i-touch); min-height: var(--cv-p-i-touch); padding: 0; border: 0; border-radius: var(--cv-p-i-radius); color: var(--cv-p-i-text-muted); background: transparent; cursor: pointer; }
+.cv-p-conversation-menu__trigger:hover, .cv-p-conversation-menu__trigger:focus-visible, .cv-p-conversation-menu__trigger[aria-expanded='true'] { color: var(--cv-p-i-text); background: var(--cv-p-i-highlight); }
+.cv-p-conversation-menu__list { z-index: 4; }
+.cv-p-message-info { min-width: 14rem; padding: 0.5rem 0.75rem 0.65rem; color: var(--cv-p-i-text); font-size: 0.85rem; cursor: default; }
+.cv-p-message-info__head { display: flex; align-items: center; justify-content: space-between; gap: 0.5rem; margin-bottom: 0.35rem; }
+.cv-p-message-info__title { font-weight: 600; }
+.cv-p-message-info__close { display: inline-flex; align-items: center; justify-content: center; padding: 0.2rem; border: 0; border-radius: var(--cv-p-i-radius); color: var(--cv-p-i-text-muted); background: transparent; cursor: pointer; }
+.cv-p-message-info__close:hover, .cv-p-message-info__close:focus-visible { color: var(--cv-p-i-text); background: var(--cv-p-i-highlight); }
+.cv-p-message-info__rows { display: grid; gap: 0.25rem; margin: 0; }
+.cv-p-message-info__row { display: flex; justify-content: space-between; gap: 1rem; }
+.cv-p-message-info__row dt { color: var(--cv-p-i-text-muted); }
+.cv-p-message-info__row dd { margin: 0; text-align: end; font-variant-numeric: tabular-nums; }
+/* Modo de seleção: caixa à esquerda de cada mensagem; a linha inteira marca e desmarca. */
+.cv-p-select-row { display: flex; align-items: center; gap: 0.6rem; width: 100%; cursor: pointer; border-radius: var(--cv-p-i-radius); }
+.cv-p-select-row[data-selected] { background: var(--cv-p-i-highlight); }
+.cv-p-select-row > .cv-p-bubble--mine { margin-inline-start: auto; }
+.cv-p-select-row > .cv-p-bubble-row { max-width: 92%; }
+.cv-p-select-row__check { flex: 0 0 auto; width: 1.1rem; height: 1.1rem; margin: 0 0 0 0.25rem; accent-color: var(--cv-p-i-accent); cursor: pointer; }
+.cv-p-selection-bar { display: flex; flex-wrap: wrap; align-items: center; gap: 0.5rem; padding: 0.6rem 0.75rem; border-top: 1px solid var(--cv-p-i-border); background: var(--cv-p-i-surface-raised); }
+.cv-p-selection-bar__count { margin-inline-end: auto; font-weight: 600; color: var(--cv-p-i-text); }
+.cv-p-selection-bar__close, .cv-p-selection-bar__action { min-height: var(--cv-p-i-touch); padding: 0 0.75rem; border: 1px solid var(--cv-p-i-border); border-radius: var(--cv-p-i-radius); color: var(--cv-p-i-text); background: transparent; font: inherit; font-size: 0.85rem; cursor: pointer; }
+.cv-p-selection-bar__close { display: inline-grid; place-items: center; min-width: var(--cv-p-i-touch); padding: 0; border-color: transparent; }
+.cv-p-selection-bar__action:disabled { color: var(--cv-p-i-text-muted); cursor: default; }
+.cv-p-selection-bar__close:hover, .cv-p-selection-bar__action:hover:not(:disabled), .cv-p-selection-bar__close:focus-visible, .cv-p-selection-bar__action:focus-visible { background: var(--cv-p-i-highlight); }
 .cv-p-attachment { display: flex; flex-direction: column; gap: 0.25rem; margin-top: 0.35rem; color: inherit; }
 .cv-p-attachment--document { flex-direction: row; justify-content: space-between; min-height: var(--cv-p-i-touch); align-items: center; text-decoration: underline; }
 .cv-p-attachment__image { display: block; max-width: 100%; max-height: 16rem; object-fit: contain; }
@@ -1390,6 +1429,7 @@
   .cv-p-thread__latest-button { animation: cv-p-latest-in 0.16s ease-out; }
   .cv-p-protocol__copy, .cv-p-search__input { transition: border-color 0.12s, background-color 0.12s; }
   .cv-p-row, .cv-p-button, .cv-p-chip, .cv-p-thread__back, .cv-p-composer__attach { transition: background-color 0.12s, border-color 0.12s; }
+  .cv-p-message-menu__trigger { transition: opacity 0.12s; }
 }
 
 /* Scrolls. Verticais: barra fina no tema. Faixas horizontais: sem barra, com esmaecimento nas bordas. O