@adatechnology/conversations-ui 0.8.0 → 0.9.0

package/src/participant/ParticipantMessageBubble.tsx

@@ -1,11 +1,10 @@
-import type { ReactNode } from 'react'
+import { useId, type ReactNode } from 'react'
 
 import type { MessageDeliveryStatus, ParticipantAttachment } from '@adatechnology/conversation-contracts'
 
-import { formatTimestamp } from '../lib/format'
-import { FailedActions, OwnStatus } from './ParticipantBubbleStatus'
-import { ParticipantMessageText } from './ParticipantMessageText'
-import { ParticipantAttachmentItem, type ResolveParticipantAttachmentUrl } from './ParticipantAttachmentItem'
+import { BubbleBody } from './ParticipantBubbleBody'
+import { RetryButton } from './ParticipantBubbleStatus'
+import type { ResolveParticipantAttachmentUrl } from './ParticipantAttachmentItem'
 import type { ParticipantConversationsLabels } from './participantLabels'
 import type { ParticipantPerspective } from './participantPerspective'
 import {
@@ -20,11 +19,11 @@ export type ParticipantMessageBubbleProps = {
   readonly labels: ParticipantConversationsLabels
   readonly confirmsRead: boolean
   readonly resolveAttachmentUrl: ResolveParticipantAttachmentUrl
-  /** Absent means no retry button, even when the message failed. */
+  /** Absent means no retry button beside the bubble, even when the message failed. */
   readonly onRetry?: () => void
-  /** Absent means no discard button. */
+  /** Absent means no discard item in the failed-message menu. */
   readonly onDiscard?: () => void
-  /** Absent means no edit button. */
+  /** Absent means no edit item in the failed-message menu. */
   readonly onEdit?: () => void
   /** Opt-in slot to the left of a received bubble; null reserves the space, absent changes nothing. */
   readonly avatar?: ReactNode
@@ -34,7 +33,7 @@ export type ParticipantMessageBubbleProps = {
   readonly perspective?: ParticipantPerspective
 }
 
-type BubbleContent = {
+export type BubbleContent = {
   readonly isMine: boolean
   readonly authorName?: string
   readonly text?: string
@@ -68,62 +67,31 @@ function describeItem(item: ParticipantTimelineItem, perspective?: ParticipantPe
   }
 }
 
-function bubbleClassName(isMine: boolean, hasTail: boolean): string {
+function bubbleClassName(isMine: boolean, hasTail: boolean, hasFailed: boolean): string {
   const classes = ['cv-p-bubble']
   if (isMine) classes.push('cv-p-bubble--mine')
+  if (hasFailed) classes.push('cv-p-bubble--failed')
   if (!hasTail) classes.push('cv-p-bubble--no-tail')
   return classes.join(' ')
 }
 
-export function ParticipantMessageBubble({
-  item,
-  labels,
-  confirmsRead,
-  resolveAttachmentUrl,
-  onRetry,
-  onDiscard,
-  onEdit,
-  avatar,
-  tail = true,
-  perspective,
-}: ParticipantMessageBubbleProps) {
+export function ParticipantMessageBubble(props: ParticipantMessageBubbleProps) {
+  const { item, labels, confirmsRead, onRetry, avatar, tail = true, perspective } = props
+  const textId = useId()
   const content = describeItem(item, perspective)
-  const { isMine } = content
-  const ownStatus = isMine
+  const ownStatus = content.isMine
     ? resolveOwnMessageStatus({ displayState: content.displayState, serverStatus: content.serverStatus, confirmsRead })
     : undefined
+  const isFailed = ownStatus === 'failed'
+  const canRetry = isFailed && onRetry !== undefined
 
   const bubble = (
-    <div className={bubbleClassName(isMine, tail)}>
-      {isMine ? (
-        <span className="cv-p-sr-only">{labels.me}</span>
-      ) : content.authorName ? (
-        <span className="cv-p-bubble__author">{content.authorName}</span>
-      ) : null}
-      {content.text ? <ParticipantMessageText text={content.text} labels={labels} /> : null}
-      {content.attachments.map((attachment) => (
-        <ParticipantAttachmentItem
-          key={attachment.id}
-          attachment={attachment}
-          resolveAttachmentUrl={resolveAttachmentUrl}
-          labels={labels}
-        />
-      ))}
-      {content.pendingFilenames.map((filename, index) => (
-        <span key={`${filename}-${index}`} className="cv-p-attachment cv-p-attachment--pending">
-          {filename}
-        </span>
-      ))}
-      <span className="cv-p-bubble__meta">
-        <time className="cv-p-bubble__time" dateTime={content.createdAt}>
-          {formatTimestamp(content.createdAt)}
-        </time>
-        {ownStatus ? <OwnStatus status={ownStatus} labels={labels} onRetry={onRetry} /> : null}
-      </span>
-      {ownStatus === 'failed' ? <FailedActions labels={labels} onDiscard={onDiscard} onEdit={onEdit} /> : null}
+    <div className={bubbleClassName(content.isMine, tail, isFailed)}>
+      {canRetry ? <RetryButton labels={labels} onRetry={onRetry} describedBy={textId} /> : null}
+      <BubbleBody {...props} content={content} ownStatus={ownStatus} textId={canRetry ? textId : undefined} />
     </div>
   )
-  if (avatar === undefined || isMine) return bubble
+  if (avatar === undefined || content.isMine) return bubble
   return (
     <div className="cv-p-bubble-row">
       <span className="cv-p-bubble-row__avatar">{avatar}</span>

package/src/participant/ParticipantMessageText.test.tsx

@@ -45,7 +45,7 @@ describe('ParticipantMessageText - links', () => {
     expect(markup).toContain('target="_blank"')
     expect(markup).toContain('<span class="cv-p-sr-only"> (opens in a new tab)</span>')
     expect(markup).toContain(
-      '<button type="button" class="cv-p-text__link-copy" aria-label="Copy https://a.com/?a=1&amp;b=2">',
+      '<button type="button" class="cv-p-text__link-copy" aria-label="Copy https://a.com/?a=1&amp;b=2" data-cv-tooltip="Copy">',
     )
   })
 

package/src/participant/ParticipantMessageText.tsx

@@ -7,6 +7,8 @@ import type { FormatBlock } from './participantMessageFormat.types'
 export type ParticipantMessageTextProps = {
   readonly text: string | null | undefined
   readonly labels: ParticipantTextLabels
+  /** Lets a control point at the text with aria-describedby; absent leaves the markup as it was. */
+  readonly id?: string
 }
 
 function renderBlock(block: FormatBlock, labels: ParticipantTextLabels, key: number) {
@@ -40,7 +42,7 @@ function renderBlock(block: FormatBlock, labels: ParticipantTextLabels, key: num
   )
 }
 
-export function ParticipantMessageText({ text, labels }: ParticipantMessageTextProps) {
+export function ParticipantMessageText({ text, labels, id }: ParticipantMessageTextProps) {
   const blocks = useMemo(() => parseParticipantMessage(text), [text])
   if (blocks.length === 0) return null
   const [only] = blocks
@@ -48,5 +50,5 @@ export function ParticipantMessageText({ text, labels }: ParticipantMessageTextP
     blocks.length === 1 && only?.kind === 'paragraph'
       ? renderInlineNodes(only.children, labels)
       : blocks.map((block, key) => renderBlock(block, labels, key))
-  return <div className="cv-p-text">{children}</div>
+  return <div className="cv-p-text" id={id}>{children}</div>
 }

package/src/participant/ParticipantProtocolBadge.tsx

@@ -39,6 +39,7 @@ export function ParticipantProtocolBadgeView({
           type="button"
           className="cv-p-protocol__copy"
           aria-label={`${labels.copyProtocol} ${protocol}`}
+          data-cv-tooltip={labels.copyProtocol}
           onClick={onCopy}
         >
           {isCopied ? <Check size={18} aria-hidden={true} /> : <Copy size={18} aria-hidden={true} />}

package/src/participant/ParticipantScrollToLatest.tsx

@@ -23,7 +23,7 @@ export function ParticipantScrollToLatest({
   if (!isVisible || onClick === undefined) return null
   return (
     <div className="cv-p-thread__latest">
-      <button type="button" className="cv-p-thread__latest-button" aria-label={label} onClick={(event) => {
+      <button type="button" className="cv-p-thread__latest-button" aria-label={label} data-cv-tooltip={label} onClick={(event) => {
           focusScrollerOf(event.currentTarget)
           onClick()
         }}

package/src/participant/ParticipantThread.tsx

@@ -1,11 +1,13 @@
-import type { ReactNode } from 'react'
+import { useRef, type ReactNode } from 'react'
 
 import type { ParticipantConversationSummary, ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
 
 import type { ConversationChannel } from '../conversationChannel'
 import type { QuickReply } from '../quickReplies/quickReply.types'
 import type { ParticipantTimelineItem } from './participantMessages'
+import { TooltipLayer } from '../Tooltip'
 import { ParticipantComposer } from './ParticipantComposer'
+import { useSuppressTouchTooltips } from './useSuppressTouchTooltips'
 import { ParticipantCopyAnnouncer, ParticipantThreadLive } from './ParticipantCopyAnnouncer'
 import type { ResolveParticipantAttachmentUrl } from './ParticipantAttachmentItem'
 import type { ParticipantPendingActions } from './participantBubbleActions'
@@ -93,23 +95,31 @@ function Footer({ props }: { readonly props: ParticipantThreadProps }) {
   )
 }
 
+function Header({ props }: { readonly props: ParticipantThreadProps }) {
+  return (
+    <ParticipantThreadHeader
+      conversation={props.conversation}
+      labels={props.labels}
+      subjectGroups={props.subjectGroups}
+      renderSubjectIcon={props.renderSubjectIcon}
+      onBack={props.onBack}
+      onOpenSubject={props.onOpenSubject}
+      counterpartLabel={props.counterpartLabel}
+      actions={props.headerActions}
+    />
+  )
+}
+
 function ThreadBody(props: ParticipantThreadProps) {
   const { conversation, labels, hasMore, onLoadOlder, renderSubjectCard } = props
   const subjectCard = renderSubjectCard?.(conversation)
   const loadView = resolveLoadView({ status: props.status, hasItems: props.items.length > 0 })
+  const rootRef = useRef<HTMLDivElement>(null)
+  useSuppressTouchTooltips(rootRef)
 
   return (
-    <div className="cv-p cv-p-thread" aria-busy={loadView.isLoading}>
-      <ParticipantThreadHeader
-        conversation={conversation}
-        labels={labels}
-        subjectGroups={props.subjectGroups}
-        renderSubjectIcon={props.renderSubjectIcon}
-        onBack={props.onBack}
-        onOpenSubject={props.onOpenSubject}
-        counterpartLabel={props.counterpartLabel}
-        actions={props.headerActions}
-      />
+    <div className="cv-p cv-p-thread" aria-busy={loadView.isLoading} ref={rootRef}>
+      <Header props={props} />
       {subjectCard ? <div className="cv-p-thread__subject-card">{subjectCard}</div> : null}
       <div className="cv-p-thread__scroll" ref={props.scroll.ref} onScroll={props.scroll.onScroll} tabIndex={-1}>
         {loadView.isLoading ? <ParticipantLoading labels={labels} /> : null}
@@ -138,6 +148,7 @@ export function ParticipantThread(props: ParticipantThreadProps) {
   return (
     <ParticipantCopyAnnouncer>
       <ThreadBody {...props} />
+      <TooltipLayer />
     </ParticipantCopyAnnouncer>
   )
 }

package/src/participant/ParticipantThreadHeader.test.tsx

@@ -102,7 +102,7 @@ describe('copy button as an icon', () => {
     const button = markup.slice(markup.indexOf('<button'), markup.indexOf('</button>'))
     expect(button).toContain('<svg')
     expect(button.replace(/<[^>]+>/g, '')).toBe('')
-    expect(markup.replace(/aria-label="[^"]*"/g, '')).not.toContain('Copy protocol')
+    expect(markup.replace(/(aria-label|data-cv-tooltip)="[^"]*"/g, '')).not.toContain('Copy protocol')
   })
 
   it('shows the short confirmation next to the icon while copied', () => {

package/src/participant/failedMenuKeyboard.ts

@@ -0,0 +1,29 @@
+import type { Dispatch, KeyboardEvent, RefObject } from 'react'
+
+import { resolveFailedMenuKey, type FailedMenuAction } from './participantFailedMenuState'
+
+type MenuKeyParams = {
+  readonly event: KeyboardEvent<HTMLElement>
+  readonly menuRef: RefObject<HTMLElement | null>
+  readonly triggerRef: RefObject<HTMLElement | null>
+  readonly dispatch: Dispatch<FailedMenuAction>
+}
+
+/** Escape is consumed here so it does not also close a host dialog or drawer around the thread. */
+export function handleFailedMenuKeyDown({ event, menuRef, triggerRef, dispatch }: MenuKeyParams): void {
+  const items = Array.from(menuRef.current?.querySelectorAll<HTMLElement>('[role="menuitem"]') ?? [])
+  const index = items.findIndex((item) => item === document.activeElement)
+  const result = resolveFailedMenuKey({ key: event.key, index, count: items.length })
+  if (!result) return
+  if (result.type === 'focus') {
+    event.preventDefault()
+    items[result.index]?.focus()
+    return
+  }
+  if (result.shouldRestoreFocus) {
+    event.preventDefault()
+    event.stopPropagation()
+    triggerRef.current?.focus()
+  }
+  dispatch({ type: 'close' })
+}

package/src/participant/participantFailedMenuDom.test.tsx

@@ -0,0 +1,154 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'bun:test'
+import { act } from 'react'
+
+import { setupDom, pressKey, type DomHarness } from '../domHarness.test-helper'
+import { ParticipantFailedMenu } from './ParticipantFailedMenu'
+import { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS as LABELS } from './participantLabels'
+
+let harness: DomHarness
+
+beforeAll(async () => {
+  harness = await setupDom()
+})
+afterAll(() => harness.teardown())
+
+const noop = (): void => undefined
+
+function mountMenu() {
+  const tree = harness.mount(
+    <div className="cv-p-thread__scroll">
+      <div className="cv-p-bubble">
+        <ParticipantFailedMenu labels={LABELS} onEdit={noop} onDiscard={noop} />
+      </div>
+    </div>,
+  )
+  const trigger = tree.container.querySelector<HTMLButtonElement>('.cv-p-failed-menu__trigger')!
+  return { ...tree, trigger }
+}
+
+function click(element: Element): void {
+  act(() => element.dispatchEvent(new MouseEvent('click', { bubbles: true })))
+}
+
+function items(container: HTMLElement): HTMLElement[] {
+  return Array.from(container.querySelectorAll<HTMLElement>('[role="menuitem"]'))
+}
+
+describe('failed menu in a DOM', () => {
+  it('opens on click, names the menu by the trigger and focuses the first item', () => {
+    const { container, trigger } = mountMenu()
+    click(trigger)
+
+    const menu = container.querySelector('[role="menu"]')!
+    expect(trigger.getAttribute('aria-expanded')).toBe('true')
+    expect(menu.getAttribute('aria-labelledby')).toBe(trigger.id)
+    expect(document.activeElement).toBe(items(container)[0])
+    expect(items(container).every((item) => item.tabIndex === -1)).toBe(true)
+    expect(trigger.hasAttribute('data-cv-tooltip')).toBe(false)
+  })
+
+  it('ArrowUp on the trigger opens the menu on the last item', () => {
+    const { container, trigger } = mountMenu()
+    act(() => trigger.focus())
+    pressKey(trigger, 'ArrowUp')
+
+    expect(document.activeElement).toBe(items(container)[1])
+  })
+
+  it('Escape closes, gives the focus back to the trigger and does not reach the host', () => {
+    const { container, trigger } = mountMenu()
+    click(trigger)
+    let hostSawEscape = false
+    const hostListener = (): void => void (hostSawEscape = true)
+    document.addEventListener('keydown', hostListener)
+
+    pressKey(items(container)[0]!, 'Escape')
+    document.removeEventListener('keydown', hostListener)
+
+    expect(container.querySelector('[role="menu"]')).toBeNull()
+    expect(document.activeElement).toBe(trigger)
+    expect(hostSawEscape).toBe(false)
+  })
+
+  it('Tab closes the menu without pulling the focus back to the trigger', () => {
+    const { container, trigger } = mountMenu()
+    click(trigger)
+    pressKey(items(container)[0]!, 'Tab')
+
+    expect(container.querySelector('[role="menu"]')).toBeNull()
+    expect(document.activeElement).not.toBe(trigger)
+  })
+
+  it('closes on a pointer press outside and keeps open on one inside', () => {
+    const { container, trigger } = mountMenu()
+    click(trigger)
+    act(() => void items(container)[0]!.dispatchEvent(new Event('pointerdown', { bubbles: true })))
+    expect(container.querySelector('[role="menu"]')).not.toBeNull()
+
+    act(() => void document.body.dispatchEvent(new Event('pointerdown', { bubbles: true })))
+    expect(container.querySelector('[role="menu"]')).toBeNull()
+  })
+
+  it('removes its document listener when unmounted with the menu open', () => {
+    const added: string[] = []
+    const removed: string[] = []
+    const add = document.addEventListener.bind(document)
+    const remove = document.removeEventListener.bind(document)
+    document.addEventListener = ((type: string, ...rest: unknown[]) => {
+      added.push(type)
+      return (add as (...args: unknown[]) => void)(type, ...rest)
+    }) as typeof document.addEventListener
+    document.removeEventListener = ((type: string, ...rest: unknown[]) => {
+      removed.push(type)
+      return (remove as (...args: unknown[]) => void)(type, ...rest)
+    }) as typeof document.removeEventListener
+
+    const { unmount, trigger } = mountMenu()
+    click(trigger)
+    unmount()
+    document.addEventListener = add
+    document.removeEventListener = remove
+
+    expect(added.filter((type) => type === 'pointerdown')).toHaveLength(1)
+    expect(removed.filter((type) => type === 'pointerdown')).toHaveLength(1)
+    expect(() => document.body.dispatchEvent(new Event('pointerdown', { bubbles: true }))).not.toThrow()
+  })
+})
+
+describe('failed menu placement in a DOM', () => {
+  let original: typeof Element.prototype.getBoundingClientRect
+
+  beforeEach(() => {
+    original = Element.prototype.getBoundingClientRect
+  })
+  afterEach(() => {
+    Element.prototype.getBoundingClientRect = original
+  })
+
+  function stubLayout(bubbleTop: number): void {
+    Element.prototype.getBoundingClientRect = function (this: Element) {
+      const top = this.classList.contains('cv-p-thread__scroll') ? 100 : this.classList.contains('cv-p-bubble') ? bubbleTop : 0
+      const height = this.getAttribute('role') === 'menu' ? 90 : 20
+      return { top, bottom: top + height, left: 0, right: 0, width: 0, height, x: 0, y: top, toJSON: () => ({}) }
+    }
+  }
+
+  it('flips below when the bubble is the first of the conversation', () => {
+    stubLayout(108)
+    const { container, trigger } = mountMenu()
+    click(trigger)
+    Element.prototype.getBoundingClientRect = original
+
+    expect(container.querySelector('.cv-p-failed-menu__list--below')).not.toBeNull()
+  })
+
+  it('stays above when there is room', () => {
+    stubLayout(500)
+    const { container, trigger } = mountMenu()
+    click(trigger)
+    Element.prototype.getBoundingClientRect = original
+
+    expect(container.querySelector('[role="menu"]')).not.toBeNull()
+    expect(container.querySelector('.cv-p-failed-menu__list--below')).toBeNull()
+  })
+})

package/src/participant/participantFailedMenuState.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'bun:test'
+
+import {
+  CLOSED_FAILED_MENU,
+  failedMenuReducer,
+  resolveFailedMenuKey,
+  resolveFailedMenuPlacement,
+  resolveFailedMenuTriggerKey,
+} from './participantFailedMenuState'
+
+describe('failed menu state', () => {
+  it('toggles open on first focus item and closes again', () => {
+    const open = failedMenuReducer(CLOSED_FAILED_MENU, { type: 'toggle' })
+    expect(open).toEqual({ isOpen: true, initialFocus: 'first' })
+    expect(failedMenuReducer(open, { type: 'toggle' })).toEqual(CLOSED_FAILED_MENU)
+  })
+
+  it('opens on the last item when asked and ignores a close while closed', () => {
+    expect(failedMenuReducer(CLOSED_FAILED_MENU, { type: 'open', initialFocus: 'last' }).initialFocus).toBe('last')
+    expect(failedMenuReducer(CLOSED_FAILED_MENU, { type: 'close' })).toBe(CLOSED_FAILED_MENU)
+  })
+})
+
+describe('failed menu keyboard', () => {
+  it('Escape closes and gives the focus back to the trigger', () => {
+    expect(resolveFailedMenuKey({ key: 'Escape', index: 0, count: 2 })).toEqual({ type: 'close', shouldRestoreFocus: true })
+  })
+
+  it('Tab closes without trapping: focus is not pulled back', () => {
+    expect(resolveFailedMenuKey({ key: 'Tab', index: 1, count: 2 })).toEqual({ type: 'close', shouldRestoreFocus: false })
+  })
+
+  it('arrows wrap around, Home and End jump', () => {
+    expect(resolveFailedMenuKey({ key: 'ArrowDown', index: 1, count: 2 })).toEqual({ type: 'focus', index: 0 })
+    expect(resolveFailedMenuKey({ key: 'ArrowUp', index: 0, count: 2 })).toEqual({ type: 'focus', index: 1 })
+    expect(resolveFailedMenuKey({ key: 'Home', index: 1, count: 2 })).toEqual({ type: 'focus', index: 0 })
+    expect(resolveFailedMenuKey({ key: 'End', index: 0, count: 2 })).toEqual({ type: 'focus', index: 1 })
+    expect(resolveFailedMenuKey({ key: 'a', index: 0, count: 2 })).toBeUndefined()
+  })
+
+  it('ArrowDown and ArrowUp open the menu from the trigger on the matching end', () => {
+    expect(resolveFailedMenuTriggerKey('ArrowDown')).toBe('first')
+    expect(resolveFailedMenuTriggerKey('ArrowUp')).toBe('last')
+    expect(resolveFailedMenuTriggerKey('Enter')).toBeUndefined()
+  })
+})
+
+describe('failed menu placement', () => {
+  it('opens above when the scroller leaves room for the menu', () => {
+    expect(resolveFailedMenuPlacement({ anchorTop: 300, scrollerTop: 100, menuHeight: 90 })).toBe('above')
+  })
+
+  it('flips below for the first bubble of the conversation, where the scroller would clip it', () => {
+    expect(resolveFailedMenuPlacement({ anchorTop: 112, scrollerTop: 100, menuHeight: 90 })).toBe('below')
+  })
+
+  it('needs the gap too: room for exactly the menu is not enough', () => {
+    expect(resolveFailedMenuPlacement({ anchorTop: 190, scrollerTop: 100, menuHeight: 90 })).toBe('below')
+    expect(resolveFailedMenuPlacement({ anchorTop: 198, scrollerTop: 100, menuHeight: 90 })).toBe('above')
+  })
+})

package/src/participant/participantFailedMenuState.ts

@@ -0,0 +1,57 @@
+export type FailedMenuFocus = 'first' | 'last'
+
+export type FailedMenuState = { readonly isOpen: boolean; readonly initialFocus: FailedMenuFocus }
+
+export type FailedMenuAction =
+  | { readonly type: 'open'; readonly initialFocus: FailedMenuFocus }
+  | { readonly type: 'close' }
+  | { readonly type: 'toggle' }
+
+export const CLOSED_FAILED_MENU: FailedMenuState = { isOpen: false, initialFocus: 'first' }
+
+export function failedMenuReducer(state: FailedMenuState, action: FailedMenuAction): FailedMenuState {
+  if (action.type === 'open') return { isOpen: true, initialFocus: action.initialFocus }
+  if (action.type === 'close') return state.isOpen ? CLOSED_FAILED_MENU : state
+  return state.isOpen ? CLOSED_FAILED_MENU : { isOpen: true, initialFocus: 'first' }
+}
+
+export type FailedMenuKeyResult =
+  | { readonly type: 'focus'; readonly index: number }
+  | { readonly type: 'close'; readonly shouldRestoreFocus: boolean }
+
+type MenuKeyParams = { readonly key: string; readonly index: number; readonly count: number }
+
+/** Roving focus inside the open menu; Tab is never trapped, it closes the menu and lets focus move on. */
+export function resolveFailedMenuKey({ key, index, count }: MenuKeyParams): FailedMenuKeyResult | undefined {
+  if (key === 'Escape') return { type: 'close', shouldRestoreFocus: true }
+  if (key === 'Tab') return { type: 'close', shouldRestoreFocus: false }
+  if (key === 'ArrowDown') return { type: 'focus', index: (index + 1) % count }
+  if (key === 'ArrowUp') return { type: 'focus', index: (index - 1 + count) % count }
+  if (key === 'Home') return { type: 'focus', index: 0 }
+  if (key === 'End') return { type: 'focus', index: count - 1 }
+  return undefined
+}
+
+/** Keys that open the menu from its trigger; Enter and Space already open it through the click. */
+export function resolveFailedMenuTriggerKey(key: string): FailedMenuFocus | undefined {
+  if (key === 'ArrowDown') return 'first'
+  if (key === 'ArrowUp') return 'last'
+  return undefined
+}
+
+export type FailedMenuPlacement = 'above' | 'below'
+
+const MENU_GAP_PX = 8
+
+type MenuPlacementParams = {
+  /** Top edge of the bubble the menu hangs from. */
+  readonly anchorTop: number
+  /** Top edge of the scroller that clips the menu. */
+  readonly scrollerTop: number
+  readonly menuHeight: number
+}
+
+/** The menu opens above its bubble; it flips below when the scroller would clip it. */
+export function resolveFailedMenuPlacement({ anchorTop, scrollerTop, menuHeight }: MenuPlacementParams): FailedMenuPlacement {
+  return anchorTop - scrollerTop >= menuHeight + MENU_GAP_PX ? 'above' : 'below'
+}

package/src/participant/participantFailedMessage.test.tsx

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { OwnStatus, RetryButton } from './ParticipantBubbleStatus'
+import { ParticipantFailedMenu } from './ParticipantFailedMenu'
+import { declarationsIn } from './participantCss.test-helper'
+import { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS as LABELS } from './participantLabels'
+
+const noop = (): void => undefined
+
+describe('failed message: markup', () => {
+  it('puts retry in a round icon button with the long text as its name, no visible text', () => {
+    const markup = renderToStaticMarkup(<RetryButton labels={LABELS} onRetry={noop} />)
+
+    expect(markup).toContain('aria-label="Failed — tap to retry"')
+    expect(markup).toContain('aria-hidden="true"')
+    expect(markup.replace(/<svg.*<\/svg>/, '')).not.toMatch(/>[A-Za-z]/)
+  })
+
+  it('keeps the meta of a failed bubble to the red icon, with the short text for screen readers only', () => {
+    const withRetry = renderToStaticMarkup(<OwnStatus status="failed" labels={LABELS} onRetry={noop} />)
+    const withoutRetry = renderToStaticMarkup(<OwnStatus status="failed" labels={LABELS} />)
+
+    expect(withRetry).not.toContain('<button')
+    expect(withRetry).toContain('cv-status-ticks--failed')
+    expect(withRetry).toContain('cv-p-sr-only">Failed<')
+    expect(withoutRetry).toContain('cv-p-bubble__status-text">Failed<')
+  })
+
+  it('renders a closed menu trigger with the menu button semantics, and no menu without handlers', () => {
+    const markup = renderToStaticMarkup(<ParticipantFailedMenu labels={LABELS} onEdit={noop} onDiscard={noop} />)
+
+    expect(markup).toContain('aria-haspopup="menu"')
+    expect(markup).toContain('aria-expanded="false"')
+    expect(markup).toContain('data-cv-tooltip="Message options"')
+    expect(markup).toContain('aria-label="Message options"')
+    expect(markup).not.toContain('role="menu"')
+    expect(renderToStaticMarkup(<ParticipantFailedMenu labels={LABELS} />)).toBe('')
+  })
+})
+
+describe('failed message: styles', () => {
+  it('hangs the retry button beside the bubble: 44px target, 2rem circle, no layout space taken', () => {
+    const button = declarationsIn('.cv-p-failed-retry')
+    const icon = declarationsIn('.cv-p-failed-retry__icon')
+
+    expect(button.get('position')).toBe('absolute')
+    expect(button.get('right')).toContain('100%')
+    expect(button.get('width')).toBe('var(--cv-p-i-touch)')
+    expect(button.get('height')).toBe('var(--cv-p-i-touch)')
+    expect(icon.get('width')).toBe('2rem')
+    expect(icon.get('border-radius')).toBe('50%')
+    expect(button.get('color')).toBe('var(--cv-p-i-danger)')
+  })
+
+  it('keeps the bubble cap of 85% by not wrapping the bubble in a row', () => {
+    expect(declarationsIn('.cv-p-bubble-row--failed').size).toBe(0)
+    expect(declarationsIn('.cv-p-bubble').get('max-width')).toBe('85%')
+  })
+
+  it('flips the menu below the bubble with a modifier', () => {
+    expect(declarationsIn('.cv-p-failed-menu__list--below').get('top')).toContain('100%')
+    expect(declarationsIn('.cv-p-failed-menu__list--below').get('bottom')).toBe('auto')
+  })
+
+  it('draws the menu with square corners, text and danger tokens, 44px items', () => {
+    expect(declarationsIn('.cv-p-failed-menu__list').get('border-radius')).toBe('var(--cv-p-i-radius)')
+    expect(declarationsIn('.cv-p-failed-menu__list').get('bottom')).toContain('100%')
+    expect(declarationsIn('.cv-p-failed-menu__item').get('color')).toBe('var(--cv-p-i-text)')
+    expect(declarationsIn('.cv-p-failed-menu__item').get('min-height')).toBe('var(--cv-p-i-touch)')
+    expect(declarationsIn('.cv-p-failed-menu__item--danger').get('color')).toBe('var(--cv-p-i-danger)')
+  })
+
+  it('keeps the trigger hit area inside the bubble padding (0.5rem), never into other rows', () => {
+    expect(declarationsIn('.cv-p-failed-menu__trigger::after').get('inset')).toBe('-0.5rem -0.4rem')
+  })
+
+  it('has no leftover action-row or bordered-retry rules', () => {
+    for (const selector of ['.cv-p-bubble__retry', '.cv-p-bubble__action', '.cv-p-bubble__actions']) {
+      expect(declarationsIn(selector).size).toBe(0)
+    }
+  })
+})

package/src/participant/participantLabels.ts

@@ -1,3 +1,5 @@
+export const DEFAULT_MESSAGE_OPTIONS_LABEL = 'Message options'
+
 export type ParticipantConversationsLabels = {
   readonly inboxTitle: string
   readonly sectionAwaiting: string
@@ -33,9 +35,12 @@ export type ParticipantConversationsLabels = {
   readonly statusRead: string
   readonly statusFailed: string
   readonly statusFailedShort: string
+  /** @deprecated No longer rendered by the default view: the retry button is icon-only and named by `statusFailed`. */
   readonly retry: string
   readonly discard: string
   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
   readonly notFound: string
   readonly loading: string
   readonly loadError: string
@@ -98,6 +103,7 @@ export const DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS: ParticipantConversationsL
   retry: 'Retry',
   discard: 'Discard',
   edit: 'Edit',
+  messageOptions: DEFAULT_MESSAGE_OPTIONS_LABEL,
   notFound: 'Conversation not found',
   loading: 'Loading…',
   loadError: 'Could not load. Check your connection and try again.',