@adatechnology/conversations-ui 0.6.1 → 0.7.0

package/src/participant/ParticipantMessageBubble.test.tsx

@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'bun:test'
+import type { ReactNode } from 'react'
 import { renderToStaticMarkup } from 'react-dom/server'
 
 import { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS } from './participantLabels'
@@ -9,7 +10,10 @@ import { ParticipantMessageBubble } from './ParticipantMessageBubble'
 const LABELS = DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS
 const resolveAttachmentUrl = async (): Promise<string> => 'https://files.example/a.png'
 
-function renderServer(message = buildMessage({ id: 'm1' }), extra: { onRetry?: () => void; confirmsRead?: boolean } = {}): string {
+function renderServer(
+  message = buildMessage({ id: 'm1' }),
+  extra: { onRetry?: () => void; confirmsRead?: boolean } = {},
+): string {
   const item: ParticipantTimelineItem = { kind: 'server', message }
   return renderToStaticMarkup(
     <ParticipantMessageBubble
@@ -82,14 +86,18 @@ describe('ParticipantMessageBubble', () => {
   })
 
   it('downgrades read to delivered when the channel does not confirm reads', () => {
-    const markup = renderServer(buildMessage({ id: 'a', direction: 'inbound', status: 'read' }), { confirmsRead: false })
+    const markup = renderServer(buildMessage({ id: 'a', direction: 'inbound', status: 'read' }), {
+      confirmsRead: false,
+    })
 
     expect(markup).toContain('cv-status-ticks--delivered')
     expect(markup).not.toContain('cv-status-ticks--read')
   })
 
   it('shows no status on the other side', () => {
-    expect(renderServer(buildMessage({ id: 'a', direction: 'outbound', status: 'read' }))).not.toContain('cv-status-ticks')
+    expect(renderServer(buildMessage({ id: 'a', direction: 'outbound', status: 'read' }))).not.toContain(
+      'cv-status-ticks',
+    )
   })
 
   it('renders pending sending and queued with their texts', () => {
@@ -152,9 +160,9 @@ describe('ParticipantMessageBubble', () => {
   it('o texto do participante não é botão nem copia ao toque', () => {
     const markup = renderServer(buildMessage({ id: 'a', direction: 'inbound' }))
 
-    expect(markup).toContain('class="cv-message-text"')
+    expect(markup).toContain('class="cv-p-text"')
     expect(markup).not.toContain('role="button"')
-    expect(markup).not.toContain('cv-message-text--copyable')
+    expect(markup).not.toContain('cv-p-text--copyable')
   })
 
   it('uses only cv-p-* classes and no Tailwind utilities', () => {
@@ -165,3 +173,42 @@ describe('ParticipantMessageBubble', () => {
     expect(markup).toContain('cv-p-')
   })
 })
+
+describe('ParticipantMessageBubble avatar slot', () => {
+  const GOLDEN_RECEIVED =
+    '<div class="cv-p-bubble"><span class="cv-p-bubble__author">Ana Souza</span><div class="cv-p-text">Hi</div><span class="cv-p-bubble__meta"><time class="cv-p-bubble__time" dateTime="2026-10-01T10:00:00.000Z">HH:MM</time></span></div>'
+
+  function renderWith(direction: 'inbound' | 'outbound', avatar?: ReactNode): string {
+    const message = buildMessage({ id: 'm', direction, authorName: 'Ana Souza', text: 'Hi' })
+    return renderToStaticMarkup(
+      <ParticipantMessageBubble
+        item={{ kind: 'server', message }}
+        labels={LABELS}
+        confirmsRead
+        resolveAttachmentUrl={resolveAttachmentUrl}
+        avatar={avatar}
+      />,
+    ).replace(/>\d\d:\d\d</, '>HH:MM<')
+  }
+
+  it('keeps the markup identical to the one before the prop existed when avatar is absent', () => {
+    expect(renderWith('outbound')).toBe(GOLDEN_RECEIVED)
+  })
+
+  it('puts the avatar to the left of a received bubble inside a row', () => {
+    const markup = renderWith('outbound', <span className="cv-p-avatar">AS</span>)
+    expect(markup).toBe(
+      `<div class="cv-p-bubble-row"><span class="cv-p-bubble-row__avatar"><span class="cv-p-avatar">AS</span></span>${GOLDEN_RECEIVED}</div>`,
+    )
+  })
+
+  it('reserves the avatar space when the slot is null', () => {
+    expect(renderWith('outbound', null)).toContain('<span class="cv-p-bubble-row__avatar"></span>')
+  })
+
+  it('never draws the avatar on an own message', () => {
+    const own = renderWith('inbound', <span className="cv-p-avatar">AS</span>)
+    expect(own).not.toContain('cv-p-avatar')
+    expect(own).not.toContain('cv-p-bubble-row')
+  })
+})

package/src/participant/ParticipantMessageBubble.tsx

@@ -1,14 +1,15 @@
+import type { ReactNode } from 'react'
+
 import type { MessageDeliveryStatus, ParticipantAttachment } from '@adatechnology/conversation-contracts'
 
-import { MessageText } from '../MessageText'
-import { StatusTicks } from '../StatusTicks'
 import { formatTimestamp } from '../lib/format'
+import { FailedActions, OwnStatus } from './ParticipantBubbleStatus'
+import { ParticipantMessageText } from './ParticipantMessageText'
 import { ParticipantAttachmentItem, type ResolveParticipantAttachmentUrl } from './ParticipantAttachmentItem'
 import type { ParticipantConversationsLabels } from './participantLabels'
 import {
   isOwnMessage,
   resolveOwnMessageStatus,
-  type ParticipantOwnMessageStatus,
   type ParticipantPendingDisplayState,
   type ParticipantTimelineItem,
 } from './participantMessages'
@@ -24,6 +25,10 @@ export type ParticipantMessageBubbleProps = {
   readonly onDiscard?: () => void
   /** Absent means no edit button. */
   readonly onEdit?: () => void
+  /** Opt-in slot to the left of a received bubble; null reserves the space, absent changes nothing. */
+  readonly avatar?: ReactNode
+  /** Speech-bubble tail on the bottom corner; false removes it. Default true. */
+  readonly tail?: boolean
 }
 
 type BubbleContent = {
@@ -60,79 +65,11 @@ function describeItem(item: ParticipantTimelineItem): BubbleContent {
   }
 }
 
-function statusText(status: ParticipantOwnMessageStatus, labels: ParticipantConversationsLabels): string {
-  const byStatus: Record<ParticipantOwnMessageStatus, string> = {
-    sending: labels.statusSending,
-    queued: labels.statusQueued,
-    sent: labels.statusSent,
-    delivered: labels.statusDelivered,
-    read: labels.statusRead,
-    failed: labels.statusFailed,
-  }
-  return byStatus[status]
-}
-
-type OwnStatusProps = {
-  readonly status: ParticipantOwnMessageStatus
-  readonly labels: ParticipantConversationsLabels
-  readonly onRetry?: () => void
-}
-
-function OwnStatus({ status, labels, onRetry }: OwnStatusProps) {
-  const ticksStatus = status === 'sending' ? 'queued' : status
-  const isVisibleText = status === 'sending' || status === 'queued' || status === 'failed'
-
-  if (status === 'failed' && onRetry) {
-    return (
-      <button type="button" className="cv-p-bubble__retry" onClick={onRetry}>
-        <StatusTicks status="failed" appearance="stylesheet" />
-        <span>{labels.statusFailed}</span>
-      </button>
-    )
-  }
-
-  const text = status === 'failed' ? labels.statusFailedShort : statusText(status, labels)
-  return (
-    <span className="cv-p-bubble__status">
-      <StatusTicks status={ticksStatus} appearance="stylesheet" />
-      <span className={isVisibleText ? 'cv-p-bubble__status-text' : 'cv-p-sr-only'}>{text}</span>
-    </span>
-  )
-}
-
-type FailedActionsProps = {
-  readonly labels: ParticipantConversationsLabels
-  readonly onDiscard?: () => void
-  readonly onEdit?: () => void
-}
-
-function FailedActions({ labels, onDiscard, onEdit }: FailedActionsProps) {
-  if (!onDiscard && !onEdit) return null
-  return (
-    <span className="cv-p-bubble__actions">
-      {onEdit ? (
-        <button type="button" className="cv-p-bubble__action" onClick={onEdit}>
-          {labels.edit}
-        </button>
-      ) : null}
-      {onDiscard ? (
-        <button type="button" className="cv-p-bubble__action" onClick={onDiscard}>
-          {labels.discard}
-        </button>
-      ) : null}
-    </span>
-  )
-}
-
-function toTextPayload(text: string, createdAt: string, isMine: boolean) {
-  return {
-    id: createdAt,
-    type: 'text' as const,
-    content: text,
-    direction: isMine ? ('inbound' as const) : ('outbound' as const),
-    sender: isMine ? ('customer' as const) : ('agent' as const),
-    timestamp: createdAt,
-  }
+function bubbleClassName(isMine: boolean, hasTail: boolean): string {
+  const classes = ['cv-p-bubble']
+  if (isMine) classes.push('cv-p-bubble--mine')
+  if (!hasTail) classes.push('cv-p-bubble--no-tail')
+  return classes.join(' ')
 }
 
 export function ParticipantMessageBubble({
@@ -143,6 +80,8 @@ export function ParticipantMessageBubble({
   onRetry,
   onDiscard,
   onEdit,
+  avatar,
+  tail = true,
 }: ParticipantMessageBubbleProps) {
   const content = describeItem(item)
   const { isMine } = content
@@ -150,16 +89,14 @@ export function ParticipantMessageBubble({
     ? resolveOwnMessageStatus({ displayState: content.displayState, serverStatus: content.serverStatus, confirmsRead })
     : undefined
 
-  return (
-    <div className={isMine ? 'cv-p-bubble cv-p-bubble--mine' : 'cv-p-bubble'}>
+  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 ? (
-        <MessageText message={toTextPayload(content.text, content.createdAt, isMine)} copyOnClick={false} appearance="stylesheet" />
-      ) : null}
+      {content.text ? <ParticipantMessageText text={content.text} labels={labels} /> : null}
       {content.attachments.map((attachment) => (
         <ParticipantAttachmentItem
           key={attachment.id}
@@ -182,4 +119,11 @@ export function ParticipantMessageBubble({
       {ownStatus === 'failed' ? <FailedActions labels={labels} onDiscard={onDiscard} onEdit={onEdit} /> : null}
     </div>
   )
+  if (avatar === undefined || isMine) return bubble
+  return (
+    <div className="cv-p-bubble-row">
+      <span className="cv-p-bubble-row__avatar">{avatar}</span>
+      {bubble}
+    </div>
+  )
 }

package/src/participant/ParticipantMessageNodes.tsx

@@ -0,0 +1,54 @@
+import type { ReactNode } from 'react'
+
+import { ParticipantCopyableToken, ParticipantLinkCopyButton } from './ParticipantCopyableToken'
+import type { ParticipantConversationsLabels } from './participantLabels'
+import type { InlineNode } from './participantMessageFormat.types'
+
+export type ParticipantTextLabels = Pick<
+  ParticipantConversationsLabels,
+  'externalLinkHint' | 'copyValue' | 'valueCopied'
+>
+
+const LINK_REL = 'noopener noreferrer nofollow ugc'
+
+function renderLink(
+  node: Extract<InlineNode, { kind: 'link' }>,
+  labels: ParticipantTextLabels,
+  key: number,
+): ReactNode {
+  const isExternal = /^https?:/i.test(node.href)
+  return (
+    <span className="cv-p-text__link-group" key={key}>
+      <a className="cv-p-text__link" href={node.href} rel={LINK_REL} target={isExternal ? '_blank' : undefined}>
+        {node.label}
+        {isExternal ? <span className="cv-p-sr-only"> ({labels.externalLinkHint})</span> : null}
+      </a>
+      <ParticipantLinkCopyButton value={node.href} labels={labels} />
+    </span>
+  )
+}
+
+export function renderInlineNodes(nodes: readonly InlineNode[], labels: ParticipantTextLabels): ReactNode[] {
+  return nodes.map((node, key): ReactNode => {
+    switch (node.kind) {
+      case 'text':
+        return node.value
+      case 'strong':
+        return <strong key={key}>{renderInlineNodes(node.children, labels)}</strong>
+      case 'em':
+        return <em key={key}>{renderInlineNodes(node.children, labels)}</em>
+      case 'del':
+        return <del key={key}>{renderInlineNodes(node.children, labels)}</del>
+      case 'code':
+        return (
+          <code className="cv-p-text__code" key={key}>
+            {node.value}
+          </code>
+        )
+      case 'link':
+        return renderLink(node, labels, key)
+      case 'copyable':
+        return <ParticipantCopyableToken key={key} copyKind={node.copyKind} value={node.value} labels={labels} />
+    }
+  })
+}

package/src/participant/ParticipantMessageText.test.tsx

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { ParticipantMessageText } from './ParticipantMessageText'
+import { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS } from './participantLabels'
+
+const LABELS = DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS
+
+function render(text: string | null | undefined, labels = LABELS): string {
+  return renderToStaticMarkup(<ParticipantMessageText text={text} labels={labels} />)
+}
+
+describe('ParticipantMessageText - markup', () => {
+  it('keeps plain text as minimal, stable markup', () => {
+    expect(render('Olá, tudo bem?')).toBe('<div class="cv-p-text">Olá, tudo bem?</div>')
+    expect(render('a\nb')).toBe('<div class="cv-p-text">a\nb</div>')
+  })
+
+  it('draws nothing for empty input', () => {
+    expect(render('')).toBe('')
+    expect(render('  ')).toBe('')
+    expect(render(null)).toBe('')
+  })
+
+  it('renders marks as semantic elements, nested', () => {
+    expect(render('*_a_* ~b~ `c`')).toBe(
+      '<div class="cv-p-text"><strong><em>a</em></strong> <del>b</del> <code class="cv-p-text__code">c</code></div>',
+    )
+  })
+
+  it('renders blocks as pre, blockquote and lists', () => {
+    expect(render('```\nx\n```')).toBe('<div class="cv-p-text"><pre class="cv-p-text__pre"><code>x</code></pre></div>')
+    expect(render('> q')).toContain('<blockquote class="cv-p-text__quote">q</blockquote>')
+    expect(render('- a\n- b')).toContain('<ul class="cv-p-text__list"><li>a</li><li>b</li></ul>')
+    expect(render('3. a')).toContain('<ol class="cv-p-text__list" start="3"><li>a</li></ol>')
+    expect(render('1. a')).toContain('<ol class="cv-p-text__list"><li>a</li></ol>')
+  })
+})
+
+describe('ParticipantMessageText - links', () => {
+  it('opens http links safely in a new tab, announces it, and offers a separate copy button', () => {
+    const markup = render('veja https://a.com/?a=1&b=2 já')
+    expect(markup).toContain('<a class="cv-p-text__link" href="https://a.com/?a=1&amp;b=2"')
+    expect(markup).toContain('rel="noopener noreferrer nofollow ugc"')
+    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">',
+    )
+  })
+
+  it('never makes the whole link a copy button', () => {
+    const markup = render('https://a.com')
+    expect(markup).toMatch(/<a [^>]*>https:\/\/a\.com<span[^>]*>[^<]*<\/span><\/a>/)
+    expect(markup).not.toMatch(/<button[^>]*><a /)
+    expect(markup.slice(markup.indexOf('<a '), markup.indexOf('</a>'))).not.toContain('<button')
+    expect(markup.indexOf('</a>')).toBeLessThan(markup.indexOf('<button'))
+  })
+
+  it('uses the host label for the new-tab hint', () => {
+    expect(render('https://a.com', { ...LABELS, externalLinkHint: 'abre em nova aba' })).toContain('(abre em nova aba)')
+  })
+
+  it('never links unsafe protocols', () => {
+    for (const text of ['javascript:alert(1)', 'data:text/html,<b>x</b>', 'vbscript:x', 'JAVASCRIPT:alert(1)']) {
+      expect(render(text)).not.toContain('<a ')
+      expect(render(text)).not.toContain('href=')
+    }
+  })
+
+  it('escapes hostile text: no script element and no event-handler attribute', () => {
+    const markup = render('<script>alert(1)</script> <img src=x onerror=alert(1)> *<b onclick=x>*')
+    expect(markup).not.toContain('<script')
+    expect(markup).not.toContain('<img')
+    expect(markup).not.toMatch(/<[a-z]+[^>]*\son[a-z]+=/i)
+    expect(markup).toContain('&lt;script&gt;')
+  })
+})
+
+describe('ParticipantMessageText - copyable tokens', () => {
+  it('renders a token as an accessible button with the value as typed', () => {
+    const markup = render('CPF 529.982.247-25')
+    expect(markup).toContain(
+      '<button type="button" class="cv-p-copyable cv-p-copyable--cpf" aria-label="Copy 529.982.247-25">529.982.247-25</button>',
+    )
+  })
+
+  it('renders one button per kind and labels it from the host labels', () => {
+    const markup = render('a@b.co (16) 99999-0000 11.222.333/0001-81', { ...LABELS, copyValue: 'Copiar' })
+    expect(markup).toContain('cv-p-copyable--email')
+    expect(markup).toContain('cv-p-copyable--phone')
+    expect(markup).toContain('cv-p-copyable--cnpj')
+    expect(markup).toContain('aria-label="Copiar a@b.co"')
+  })
+
+  it('does not highlight code, money, dates or short numbers', () => {
+    expect(render('`529.982.247-25`')).not.toContain('cv-p-copyable')
+    expect(render('R$ 1.234,56 em 10/10/2026, NF 4521 (12345)')).not.toContain('cv-p-copyable')
+  })
+
+  it('uses no live region of its own and no innerHTML', () => {
+    const markup = render('a@b.co https://a.com')
+    expect(markup).not.toContain('aria-live')
+    expect(markup).not.toContain('dangerouslySetInnerHTML')
+  })
+})

package/src/participant/ParticipantMessageText.tsx

@@ -0,0 +1,52 @@
+import { useMemo } from 'react'
+
+import { renderInlineNodes, type ParticipantTextLabels } from './ParticipantMessageNodes'
+import { parseParticipantMessage } from './participantMessageFormat'
+import type { FormatBlock } from './participantMessageFormat.types'
+
+export type ParticipantMessageTextProps = {
+  readonly text: string | null | undefined
+  readonly labels: ParticipantTextLabels
+}
+
+function renderBlock(block: FormatBlock, labels: ParticipantTextLabels, key: number) {
+  if (block.kind === 'paragraph') return <span key={key}>{renderInlineNodes(block.children, labels)}</span>
+  if (block.kind === 'pre') {
+    return (
+      <pre className="cv-p-text__pre" key={key}>
+        <code>{block.value}</code>
+      </pre>
+    )
+  }
+  if (block.kind === 'quote') {
+    return (
+      <blockquote className="cv-p-text__quote" key={key}>
+        {renderInlineNodes(block.children, labels)}
+      </blockquote>
+    )
+  }
+  const items = block.items.map((item, index) => <li key={index}>{renderInlineNodes(item, labels)}</li>)
+  if (block.ordered) {
+    return (
+      <ol className="cv-p-text__list" key={key} start={block.start === 1 ? undefined : block.start}>
+        {items}
+      </ol>
+    )
+  }
+  return (
+    <ul className="cv-p-text__list" key={key}>
+      {items}
+    </ul>
+  )
+}
+
+export function ParticipantMessageText({ text, labels }: ParticipantMessageTextProps) {
+  const blocks = useMemo(() => parseParticipantMessage(text), [text])
+  if (blocks.length === 0) return null
+  const [only] = blocks
+  const children =
+    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>
+}

package/src/participant/ParticipantProtocolBadge.tsx

@@ -1,3 +1,4 @@
+import { Check, Copy } from 'lucide-react'
 import { useEffect, useReducer } from 'react'
 
 import type { ParticipantConversationsLabels } from './participantLabels'
@@ -29,18 +30,25 @@ export function ParticipantProtocolBadgeView({
   const { isCopied, copyCount } = copyState
   return (
     <>
-      <div className="cv-p-protocol cv-p-protocol--header">
+      <span className="cv-p-protocol cv-p-protocol--header">
         <span className="cv-p-protocol__code">
           <span className="cv-p-sr-only">{labels.protocolPrefix} </span>
           {protocol}
         </span>
-        <button type="button" className="cv-p-protocol__copy" onClick={onCopy}>
-          <span aria-hidden="true">{isCopied ? labels.protocolCopied : labels.copyProtocol}</span>
-          <span className="cv-p-sr-only">
-            {labels.copyProtocol} {protocol}
-          </span>
+        <button
+          type="button"
+          className="cv-p-protocol__copy"
+          aria-label={`${labels.copyProtocol} ${protocol}`}
+          onClick={onCopy}
+        >
+          {isCopied ? <Check size={18} aria-hidden={true} /> : <Copy size={18} aria-hidden={true} />}
+          {isCopied ? (
+            <span className="cv-p-protocol__copied" aria-hidden="true">
+              {labels.protocolCopied}
+            </span>
+          ) : null}
         </button>
-      </div>
+      </span>
       <div className="cv-p-sr-only" role="status" aria-live="polite">
         {isCopied ? <span key={copyCount}>{labels.protocolCopied}</span> : null}
       </div>

package/src/participant/ParticipantProtocolView.test.tsx

@@ -148,16 +148,14 @@ describe('copy button', () => {
       />,
     )
 
-  it('has a default visible label starting the accessible name', () => {
+  it('has a default accessible name that starts with the visible action and carries the code', () => {
     expect(LABELS.copyProtocol).toBe('Copy protocol')
-    const markup = render(false)
-    expect(markup).toContain('<span aria-hidden="true">Copy protocol</span>')
-    expect(markup).toContain('<span class="cv-p-sr-only">Copy protocol 261009-K7M2</span>')
+    expect(render(false)).toContain('aria-label="Copy protocol 261009-K7M2"')
   })
 
-  it('swaps the visible text for the confirmation while copied, hidden from assistive tech', () => {
+  it('shows the confirmation next to the icon while copied, hidden from assistive tech', () => {
     const markup = render(true)
-    expect(markup).toContain(`<span aria-hidden="true">${LABELS.protocolCopied}</span>`)
+    expect(markup).toContain(`<span class="cv-p-protocol__copied" aria-hidden="true">${LABELS.protocolCopied}</span>`)
     expect(markup).toContain(`<span>${LABELS.protocolCopied}</span></div>`)
   })
 

package/src/participant/ParticipantScrollToLatest.test.tsx

@@ -0,0 +1,153 @@
+import { describe, expect, it } from 'bun:test'
+import type { ReactElement } from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import {
+  buildConversation,
+  buildMessage,
+  findForeignClassTokens,
+  findUtilityClassTokens,
+} from './participantFixtures.test-helper'
+import { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS } from './participantLabels'
+import { ParticipantScrollToLatest } from './ParticipantScrollToLatest'
+import { ParticipantThread, type ParticipantThreadProps } from './ParticipantThread'
+
+const LABEL = DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS.scrollToLatest
+
+function renderButton(overrides: Partial<Parameters<typeof ParticipantScrollToLatest>[0]> = {}): string {
+  return renderToStaticMarkup(
+    <ParticipantScrollToLatest
+      label={LABEL}
+      isAwayFromBottom
+      hasMessages
+      newMessagesCount={0}
+      onClick={() => undefined}
+      {...overrides}
+    />,
+  )
+}
+
+function renderThread(overrides: Partial<ParticipantThreadProps> = {}): string {
+  return renderToStaticMarkup(
+    <ParticipantThread
+      conversation={buildConversation({ subjectId: '1' })}
+      items={[{ kind: 'server', message: buildMessage({ id: 'a', createdAt: '2026-10-01T10:00:00.000Z' }) }]}
+      hasMore={false}
+      labels={DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS}
+      resolveAttachmentUrl={async () => 'https://files.example/a'}
+      draft={{ value: '', onChange: () => undefined, files: [], onFilesChange: () => undefined }}
+      onSend={() => undefined}
+      status="ready"
+      refresh={() => undefined}
+      scroll={{
+        ref: { current: null },
+        onScroll: () => undefined,
+        isAwayFromBottom: true,
+        scrollToLatest: () => undefined,
+      }}
+      newMessagesCount={0}
+      isSending={false}
+      {...overrides}
+    />,
+  )
+}
+
+describe('ParticipantScrollToLatest', () => {
+  it('has a generic English default label', () => {
+    expect(LABEL).toBe('Scroll to latest message')
+  })
+
+  it('draws nothing near the end of the conversation', () => {
+    expect(renderButton({ isAwayFromBottom: false })).toBe('')
+  })
+
+  it('draws nothing without messages', () => {
+    expect(renderButton({ hasMessages: false })).toBe('')
+  })
+
+  it('is a named button that does not submit anything', () => {
+    const markup = renderButton()
+    expect(markup).toContain(`aria-label="${LABEL}"`)
+    expect(markup).toContain('type="button"')
+    expect(markup).toContain('class="cv-p-thread__latest-button"')
+  })
+
+  it('keeps the icon decorative', () => {
+    expect(renderButton()).toContain('aria-hidden="true"')
+  })
+
+  it('shows the count of new incoming messages in a badge hidden from the accessibility tree', () => {
+    expect(renderButton({ newMessagesCount: 3 })).toContain(
+      '<span class="cv-p-thread__latest-badge" aria-hidden="true">3</span>',
+    )
+  })
+
+  it('has no badge with zero new messages', () => {
+    expect(renderButton({ newMessagesCount: 0 })).not.toContain('cv-p-thread__latest-badge')
+  })
+
+  it('has the aria-label exactly as the label, without the count', () => {
+    expect(renderButton({ newMessagesCount: 3 })).toContain(`aria-label="${LABEL}"`)
+  })
+})
+
+describe('ParticipantScrollToLatest focus', () => {
+  it('moves focus to the scroller before scrolling, since the button unmounts on click', () => {
+    const order: string[] = []
+    const root = ParticipantScrollToLatest({
+      label: LABEL,
+      isAwayFromBottom: true,
+      hasMessages: true,
+      newMessagesCount: 0,
+      onClick: () => void order.push('scroll'),
+    }) as ReactElement<{ children: ReactElement<{ onClick: (event: unknown) => void }> }>
+    const button = root.props.children
+    button.props.onClick({
+      currentTarget: { closest: () => ({ focus: () => void order.push('focus') }) },
+    })
+    expect(order).toEqual(['focus', 'scroll'])
+  })
+
+  it('makes the scroller focusable by script only', () => {
+    expect(renderThread()).toMatch(/<div class="cv-p-thread__scroll" tabindex="-1">/)
+  })
+})
+
+describe('ParticipantThread with the scroll-to-latest button', () => {
+  it('draws the button inside the scroller, after the messages', () => {
+    const markup = renderThread()
+    const scroller = markup.indexOf('cv-p-thread__scroll')
+    expect(markup.indexOf('cv-p-thread__latest-button')).toBeGreaterThan(markup.indexOf('cv-p-thread__messages'))
+    expect(markup.indexOf('cv-p-thread__latest-button')).toBeGreaterThan(scroller)
+    expect(markup.indexOf('cv-p-thread__latest-button')).toBeLessThan(markup.indexOf('cv-p-thread__live'))
+  })
+
+  it('does not draw it while the reader is at the end', () => {
+    const scroll = { ref: { current: null }, onScroll: () => undefined, isAwayFromBottom: false }
+    expect(renderThread({ scroll })).not.toContain('cv-p-thread__latest')
+  })
+
+  it('does not draw it for a host that gives no away state', () => {
+    expect(renderThread({ scroll: { ref: { current: null }, onScroll: () => undefined } })).not.toContain(
+      'cv-p-thread__latest',
+    )
+  })
+
+  it('announces only the new-messages label, never the count or the button label', () => {
+    const markup = renderThread({ newMessagesCount: 2 })
+    expect(markup).toContain('role="status" aria-live="polite">New messages</div>')
+    expect(markup.split('New messages').length - 1).toBe(1)
+    expect(markup.match(/aria-live/g)).toHaveLength(1)
+  })
+
+  it('lets the host translate the label', () => {
+    const labels = { ...DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS, scrollToLatest: 'Ir para a última mensagem' }
+    expect(renderThread({ labels })).toContain('aria-label="Ir para a última mensagem"')
+  })
+
+  it('stays inside the participant namespace with no utility classes', () => {
+    const markup = renderThread({ newMessagesCount: 2 })
+    expect(findUtilityClassTokens(markup)).toEqual([])
+    expect(findForeignClassTokens(markup)).toEqual([])
+  })
+})