@adatechnology/conversations-ui 0.6.1 → 0.7.0

package/src/participant/participantMessageLinks.ts

@@ -0,0 +1,54 @@
+import type { InlineAtom } from './participantMessageFormat.types'
+
+const ALLOWED_LINK_PROTOCOLS: ReadonlySet<string> = new Set(['http:', 'https:', 'mailto:', 'tel:'])
+const URL_PATTERN = /https?:\/\/[^\s<>`\u0000-\u001f]+/giu
+const TRAILING_PUNCTUATION = '.,;:!?*_~\'"]}>'
+
+export function isAllowedLinkHref(href: string): boolean {
+  try {
+    const url = new URL(href)
+    return ALLOWED_LINK_PROTOCOLS.has(url.protocol) && url.username === '' && url.password === ''
+  } catch {
+    return false
+  }
+}
+
+function isAlphanumeric(character: string | undefined): boolean {
+  return character !== undefined && /[\p{L}\p{N}]/u.test(character)
+}
+
+function countOf(text: string, character: string): number {
+  let count = 0
+  for (const current of text) if (current === character) count += 1
+  return count
+}
+
+function trimUrl(raw: string): string {
+  let openCount = countOf(raw, '(')
+  let closeCount = countOf(raw, ')')
+  let end = raw.length
+  while (end > 0) {
+    const last = raw.charAt(end - 1)
+    if (last === ')' && closeCount > openCount) closeCount -= 1
+    else if (!TRAILING_PUNCTUATION.includes(last)) break
+    end -= 1
+  }
+  return raw.slice(0, end)
+}
+
+function toLinkAtom(text: string, start: number, raw: string): InlineAtom | undefined {
+  const label = trimUrl(raw)
+  if (/^https?:\/\/$/i.test(label) || isAlphanumeric(text[start - 1])) return undefined
+  const href = label.replace(/^https?/i, (scheme) => scheme.toLowerCase())
+  if (!isAllowedLinkHref(href)) return undefined
+  return { start, end: start + label.length, node: { kind: 'link', href, label } }
+}
+
+export function findLinkAtoms(text: string): InlineAtom[] {
+  const atoms: InlineAtom[] = []
+  for (const match of text.matchAll(URL_PATTERN)) {
+    const atom = toLinkAtom(text, match.index, match[0])
+    if (atom) atoms.push(atom)
+  }
+  return atoms
+}

package/src/participant/participantMessageTextStyle.test.ts

@@ -0,0 +1,137 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'bun:test'
+
+import { splitBlocks } from '../cssBlocks.test-helper'
+import { PARTICIPANT_CSS, declarationsIn } from './participantCss.test-helper'
+
+const TEXT_SELECTOR = /\.cv-p-(text|copyable)/
+
+function collectBlocks(css: string): string[] {
+  return splitBlocks(css).flatMap(({ prelude, body }) => {
+    if (body === undefined) return []
+    if (prelude.startsWith('@media')) return collectBlocks(body)
+    return TEXT_SELECTOR.test(prelude) ? [`${prelude} {${body}}`] : []
+  })
+}
+
+function forcedColorsBody(): string {
+  return splitBlocks(PARTICIPANT_CSS)
+    .filter(({ prelude }) => prelude === '@media (forced-colors: active)')
+    .map(({ body }) => body ?? '')
+    .join('\n')
+}
+
+const TEXT_CSS = collectBlocks(PARTICIPANT_CSS).join('\n')
+
+describe('participant message text - stylesheet', () => {
+  it('has rules for the text, the code, the block, the quote and the tokens', () => {
+    expect(collectBlocks(PARTICIPANT_CSS).length).toBeGreaterThan(12)
+  })
+
+  it('uses no fixed colour and no url()', () => {
+    expect(TEXT_CSS).not.toMatch(/#[0-9a-f]{3,8}\b/i)
+    expect(TEXT_CSS).not.toMatch(/\b(rgb|rgba|hsl|hsla)\(/i)
+    expect(TEXT_CSS).not.toContain('url(')
+  })
+
+  it('keeps the text selectable and the typography of the old text', () => {
+    const text = declarationsIn('.cv-p-text')
+    expect(text.get('user-select')).toBe('text')
+    expect(text.get('white-space')).toBe('pre-wrap')
+    expect(text.get('font-size')).toBe('14.2px')
+    expect(text.get('line-height')).toBe('19px')
+  })
+
+  it('styles inline code and the block from the tokens', () => {
+    expect(declarationsIn('.cv-p-text__code').get('background')).toBe(
+      declarationsIn('.cv-p-text__pre').get('background'),
+    )
+    expect(declarationsIn('.cv-p-text__code').get('background')).toContain('color-mix(in srgb, var(--cv-p-i-border)')
+    expect(declarationsIn('.cv-p-text__code').get('border-radius')).toBe('var(--cv-p-i-radius)')
+    const pre = declarationsIn('.cv-p-text__pre')
+    expect(pre.get('overflow-x')).toBe('auto')
+    expect(pre.get('white-space')).toBe('pre')
+    expect(pre.get('border-inline-start')).toBe('2px solid var(--cv-p-i-accent)')
+    expect(pre.get('scrollbar-color')).toBe('var(--cv-p-i-scrollbar-thumb) transparent')
+  })
+
+  it('styles the quote, the lists and the links from the tokens', () => {
+    const quote = declarationsIn('.cv-p-text__quote')
+    expect(quote.get('border-inline-start')).toBe('3px solid var(--cv-p-i-border)')
+    expect(quote.get('color')).toBe('var(--cv-p-i-text-muted)')
+    expect(declarationsIn('.cv-p-text__list').get('padding-inline-start')).toBe('1.25rem')
+    const link = declarationsIn('.cv-p-text__link')
+    expect(link.get('color')).toBe('var(--cv-p-i-accent)')
+    expect(link.get('text-decoration')).toBe('underline')
+    expect(link.get('overflow-wrap')).toBe('anywhere')
+    expect(declarationsIn('.cv-p-text__link:focus-visible').get('outline')).toBe('2px solid var(--cv-p-i-accent)')
+  })
+
+  it('highlights tokens discreetly with the accent', () => {
+    const token = declarationsIn('.cv-p-copyable')
+    expect(token.get('background')).toBe('color-mix(in srgb, var(--cv-p-i-accent) 14%, transparent)')
+    expect(token.get('border-bottom')).toBe('1px dotted var(--cv-p-i-accent)')
+    expect(token.get('font-family')).toContain('monospace')
+    expect(token.get('border-radius')).toBe('var(--cv-p-i-radius)')
+    expect(token.get('user-select')).toBe('text')
+  })
+
+  it('keeps the tap target of tokens and the copy icon from invading neighbouring lines or the link text', () => {
+    expect(declarationsIn('.cv-p').get('--cv-p-i-touch')).toBe('2.75rem')
+    for (const selector of ['.cv-p-copyable::after', '.cv-p-text__link-copy::after']) {
+      expect(declarationsIn(selector).get('min-height')).toBe('1.5rem')
+    }
+    const icon = declarationsIn('.cv-p-text__link-copy::after')
+    expect(icon.get('inset-inline')).toBe('0 auto')
+    expect(icon.get('min-width')).toBe('var(--cv-p-i-touch)')
+    expect(icon.get('margin-inline-start')).toBeUndefined()
+    expect(declarationsIn('.cv-p-copyable').get('display')).toBe('inline')
+    expect(declarationsIn('.cv-p-copyable').get('position')).toBe('relative')
+  })
+
+  it('gets borders instead of backgrounds under forced colors', () => {
+    const forced = forcedColorsBody()
+    expect(forced).toContain('.cv-p-copyable')
+    expect(forced).toContain('.cv-p-text__pre')
+    expect(declarationsIn('.cv-p-copyable', forced).get('border')).toBe('1px solid')
+    expect(declarationsIn('.cv-p-copyable', forced).get('background')).toBe('none')
+  })
+})
+
+describe('participant message text - hygiene', () => {
+  const FILES = [
+    'participantMessageFormat.ts',
+    'participantMessageInline.ts',
+    'participantMessageAtoms.ts',
+    'participantMessageLinks.ts',
+    'participantMessageCopyables.ts',
+    'participantDocuments.ts',
+    'ParticipantMessageText.tsx',
+    'ParticipantMessageNodes.tsx',
+    'ParticipantCopyableToken.tsx',
+    'ParticipantCopyAnnouncer.tsx',
+    'useParticipantCopyFeedback.ts',
+  ] as const
+  const sources = FILES.map((file) => ({ file, source: readFileSync(join(import.meta.dir, file), 'utf8') }))
+
+  it('stays within 200 lines per file', () => {
+    for (const { file, source } of sources) {
+      expect({ file, ok: source.split('\n').length <= 200 }).toEqual({ file, ok: true })
+    }
+  })
+
+  it('never sets inner HTML, never uses any, never reuses the shared MessageText', () => {
+    for (const { source } of sources) {
+      expect(source).not.toMatch(/innerHTML|dangerouslySetInnerHTML|:\s*any\b|as any|MessageText\b.*from '\.\.\//)
+      expect(source).not.toContain('whatsapp-formatting')
+    }
+  })
+
+  it('has no Tailwind utilities and no vocabulary from a specific product', () => {
+    for (const { source } of sources) {
+      expect(source).not.toMatch(/className="[^"]*\b(flex|grid|p-\d|m-\d|text-(sm|xs|lg)|bg-\w+)\b/)
+      expect(source).not.toMatch(/\b(carga|entrega|frete|cte|nf-?e|transport\w*|motorista|viagem|trip|driver)\b/i)
+    }
+  })
+})

package/src/participant/participantScrollFocus.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'bun:test'
+
+import { SCROLLER_SELECTOR, focusScrollerOf } from './participantScrollFocus'
+
+describe('focusScrollerOf', () => {
+  it('moves focus to the scroller ancestor without scrolling it', () => {
+    const calls: unknown[] = []
+    const selectors: string[] = []
+    focusScrollerOf({
+      closest: (selector) => {
+        selectors.push(selector)
+        return { focus: (options) => void calls.push(options) }
+      },
+    })
+    expect(selectors).toEqual([SCROLLER_SELECTOR])
+    expect(calls).toEqual([{ preventScroll: true }])
+  })
+
+  it('does nothing when there is no scroller', () => {
+    expect(() => focusScrollerOf({ closest: () => null })).not.toThrow()
+  })
+})

package/src/participant/participantScrollFocus.ts

@@ -0,0 +1,10 @@
+export type FocusableAncestorSource = {
+  readonly closest: (selector: string) => { readonly focus: (options: { preventScroll: boolean }) => void } | null
+}
+
+export const SCROLLER_SELECTOR = '.cv-p-thread__scroll'
+
+/** The button unmounts on click; moving focus first keeps it from falling to the body. */
+export function focusScrollerOf(button: FocusableAncestorSource): void {
+  button.closest(SCROLLER_SELECTOR)?.focus({ preventScroll: true })
+}

package/src/participant/participantScrollView.test.ts

@@ -0,0 +1,74 @@
+import { readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'bun:test'
+
+import { resolveScrollToLatestView, scrollIntoViewOptions, scrollToLatestOptions } from './participantScrollView'
+
+describe('resolveScrollToLatestView', () => {
+  it('is hidden while the reader is near the end', () => {
+    expect(resolveScrollToLatestView({ isAwayFromBottom: false, newMessagesCount: 0, hasMessages: true })).toEqual({
+      isVisible: false,
+      badge: undefined,
+    })
+  })
+
+  it('is hidden when there is nothing to scroll to', () => {
+    expect(
+      resolveScrollToLatestView({ isAwayFromBottom: true, newMessagesCount: 0, hasMessages: false }).isVisible,
+    ).toBe(false)
+  })
+
+  it('is visible without a badge when away and nothing new arrived', () => {
+    expect(resolveScrollToLatestView({ isAwayFromBottom: true, newMessagesCount: 0, hasMessages: true })).toEqual({
+      isVisible: true,
+      badge: undefined,
+    })
+  })
+
+  it('carries the count of new incoming messages as the badge', () => {
+    expect(resolveScrollToLatestView({ isAwayFromBottom: true, newMessagesCount: 3, hasMessages: true }).badge).toBe(
+      '3',
+    )
+  })
+
+  it('caps a large count', () => {
+    expect(resolveScrollToLatestView({ isAwayFromBottom: true, newMessagesCount: 100, hasMessages: true }).badge).toBe(
+      '99+',
+    )
+    expect(resolveScrollToLatestView({ isAwayFromBottom: true, newMessagesCount: 99, hasMessages: true }).badge).toBe(
+      '99',
+    )
+  })
+})
+
+describe('scroll options', () => {
+  it('scrolls to the end of the list, smooth only without reduced motion', () => {
+    expect(scrollToLatestOptions({ scrollHeight: 900, isReducedMotion: false })).toEqual({
+      top: 900,
+      behavior: 'smooth',
+    })
+    expect(scrollToLatestOptions({ scrollHeight: 900, isReducedMotion: true })).toEqual({ top: 900, behavior: 'auto' })
+  })
+
+  it('reveals the active chip with the nearest rule and no animation under reduced motion', () => {
+    expect(scrollIntoViewOptions(false)).toEqual({ block: 'nearest', inline: 'nearest', behavior: 'smooth' })
+    expect(scrollIntoViewOptions(true)).toEqual({ block: 'nearest', inline: 'nearest', behavior: 'auto' })
+  })
+})
+
+describe('the near-the-end threshold has one owner', () => {
+  it('is declared only in participantScroll.ts', () => {
+    const sources = readdirSync(import.meta.dir).filter(
+      (name) => /\.tsx?$/.test(name) && !/\.test(-helper)?\.tsx?$/.test(name),
+    )
+    const declaring = sources.filter((name) =>
+      /NEAR_BOTTOM_THRESHOLD_PX\s*=/.test(readFileSync(join(import.meta.dir, name), 'utf8')),
+    )
+    expect(declaring).toEqual(['participantScroll.ts'])
+  })
+
+  it('is not re-derived by the scroll-to-latest rule', () => {
+    const source = readFileSync(join(import.meta.dir, 'participantScrollView.ts'), 'utf8')
+    expect(source).not.toMatch(/scrollTop|clientHeight|threshold/i)
+  })
+})

package/src/participant/participantScrollView.ts

@@ -0,0 +1,38 @@
+const BADGE_CAP = 99
+
+export type ScrollToLatestViewParams = {
+  /** Already decided by shouldStickToBottom; this rule never looks at pixels. */
+  readonly isAwayFromBottom: boolean
+  readonly newMessagesCount: number
+  readonly hasMessages: boolean
+}
+
+export type ScrollToLatestView = {
+  readonly isVisible: boolean
+  readonly badge: string | undefined
+}
+
+export type ScrollToLatestOptionsParams = {
+  readonly scrollHeight: number
+  readonly isReducedMotion: boolean
+}
+
+export function resolveScrollToLatestView(params: ScrollToLatestViewParams): ScrollToLatestView {
+  const { isAwayFromBottom, newMessagesCount, hasMessages } = params
+  if (!isAwayFromBottom || !hasMessages) return { isVisible: false, badge: undefined }
+  if (newMessagesCount <= 0) return { isVisible: true, badge: undefined }
+  return { isVisible: true, badge: newMessagesCount > BADGE_CAP ? `${BADGE_CAP}+` : String(newMessagesCount) }
+}
+
+export function scrollToLatestOptions(params: ScrollToLatestOptionsParams): ScrollToOptions {
+  return { top: params.scrollHeight, behavior: params.isReducedMotion ? 'auto' : 'smooth' }
+}
+
+export function scrollIntoViewOptions(isReducedMotion: boolean): ScrollIntoViewOptions {
+  return { block: 'nearest', inline: 'nearest', behavior: isReducedMotion ? 'auto' : 'smooth' }
+}
+
+export function readPrefersReducedMotion(): boolean {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return false
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches
+}

package/src/participant/participantScrollbars.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from 'bun:test'
+
+import { PARTICIPANT_CSS, declarationsIn, mediaBody, toRem } from './participantCss.test-helper'
+
+const VERTICAL_AREAS = ['.cv-p-thread__scroll', '.cv-p-inbox', '.cv-p-composer__input']
+const HORIZONTAL_STRIPS = ['.cv-p-filters', '.cv-p-quick']
+const NO_PREFERENCE = '(prefers-reduced-motion: no-preference)'
+const FORCED_COLORS = '(forced-colors: active)'
+const WEBKIT_GUARD = 'not (forced-colors: active)'
+
+function webkitRules(selector: string): Map<string, string> {
+  return declarationsIn(`${selector}::-webkit-scrollbar`, mediaBody(WEBKIT_GUARD))
+}
+
+describe.each(VERTICAL_AREAS)('vertical scroller %s', (selector) => {
+  const declarations = declarationsIn(selector)
+
+  it('has a thin themed scrollbar from the tokens', () => {
+    expect(declarations.get('scrollbar-width')).toBe('thin')
+    expect(declarations.get('scrollbar-color')).toBe('var(--cv-p-i-scrollbar-thumb) transparent')
+  })
+
+  it('does not chain the scroll to the page', () => {
+    expect(declarations.get('overscroll-behavior-y')).toBe('contain')
+  })
+
+  it('has a 6px track-less webkit scrollbar with a rounded thumb and no arrows', () => {
+    expect(webkitRules(selector).get('width')).toBe('6px')
+    expect(webkitRules(selector).get('height')).toBe('6px')
+    const track = declarationsIn(`${selector}::-webkit-scrollbar-track`, mediaBody(WEBKIT_GUARD))
+    expect(track.get('background')).toBe('transparent')
+    const thumb = declarationsIn(`${selector}::-webkit-scrollbar-thumb`, mediaBody(WEBKIT_GUARD))
+    expect(thumb.get('background-color')).toBe('var(--cv-p-i-scrollbar-thumb)')
+    expect(thumb.get('border-radius')).toBe('var(--cv-p-i-radius)')
+    const buttons = declarationsIn(`${selector}::-webkit-scrollbar-button`, mediaBody(WEBKIT_GUARD))
+    expect(buttons.get('display')).toBe('none')
+  })
+
+  it('highlights the thumb with the accent on hover and drag', () => {
+    const hover = declarationsIn(`${selector}::-webkit-scrollbar-thumb:hover`, mediaBody(WEBKIT_GUARD))
+    const active = declarationsIn(`${selector}::-webkit-scrollbar-thumb:active`, mediaBody(WEBKIT_GUARD))
+    expect(hover.get('background-color')).toBe('var(--cv-p-i-scrollbar-thumb-hover)')
+    expect(active.get('background-color')).toBe('var(--cv-p-i-scrollbar-thumb-hover)')
+  })
+
+  it('goes back to the system scrollbar under forced colors', () => {
+    const forced = declarationsIn(selector, mediaBody(FORCED_COLORS))
+    expect(forced.get('scrollbar-color')).toBe('auto')
+    expect(forced.get('scrollbar-width')).toBe('auto')
+  })
+})
+
+describe('scrollbar tokens', () => {
+  const root = declarationsIn('.cv-p')
+
+  it('derive from the existing tokens and are overridable', () => {
+    expect(root.get('--cv-p-i-scrollbar-thumb')).toBe('var(--cv-p-scrollbar-thumb, var(--cv-p-i-border))')
+    expect(root.get('--cv-p-i-scrollbar-thumb-hover')).toBe('var(--cv-p-scrollbar-thumb-hover, var(--cv-p-i-accent))')
+  })
+})
+
+describe('thread scrollbar does not move the bubbles', () => {
+  it('reserves no gutter', () => {
+    expect(declarationsIn('.cv-p-thread__scroll').get('scrollbar-gutter')).toBeUndefined()
+    expect(declarationsIn('.cv-p-inbox').get('scrollbar-gutter')).toBeUndefined()
+  })
+})
+
+describe.each(HORIZONTAL_STRIPS)('horizontal strip %s', (selector) => {
+  const declarations = declarationsIn(selector)
+
+  it('hides the scrollbar everywhere', () => {
+    expect(declarations.get('scrollbar-width')).toBe('none')
+    expect(declarationsIn(`${selector}::-webkit-scrollbar`).get('display')).toBe('none')
+  })
+
+  it('fades both edges to hint that it scrolls', () => {
+    const mask = declarations.get('mask-image') ?? ''
+    expect(mask).toContain('linear-gradient(to right')
+    expect(mask).toContain('transparent')
+    expect(declarations.get('-webkit-mask-image')).toBe(mask)
+  })
+
+  it('snaps with proximity and does not chain sideways', () => {
+    expect(declarations.get('scroll-snap-type')).toBe('x proximity')
+    expect(declarations.get('overscroll-behavior-x')).toBe('contain')
+    expect(declarations.get('-webkit-overflow-scrolling')).toBe('touch')
+  })
+
+  it('keeps the first chip clear of the fade', () => {
+    expect(declarations.get('scroll-padding-inline')).toBe('var(--cv-p-i-fade)')
+    expect(declarations.get('padding-inline')).toBe('var(--cv-p-i-fade)')
+    expect(toRem(declarationsIn(selector).get('--cv-p-i-fade'))).toBeGreaterThanOrEqual(0.75)
+    expect(declarationsIn(`${selector} > .cv-p-chip`).get('scroll-snap-align')).toBe('start')
+  })
+
+  it('drops the mask under forced colors', () => {
+    const forced = declarationsIn(selector, mediaBody(FORCED_COLORS))
+    expect(forced.get('mask-image')).toBe('none')
+    expect(forced.get('-webkit-mask-image')).toBe('none')
+  })
+})
+
+describe('smooth scrolling', () => {
+  const SMOOTH_AREAS = ['.cv-p-inbox', '.cv-p-filters', '.cv-p-quick']
+
+  it.each(SMOOTH_AREAS)('%s is smooth only when motion is welcome', (selector) => {
+    expect(declarationsIn(selector, mediaBody(NO_PREFERENCE)).get('scroll-behavior')).toBe('smooth')
+    expect(declarationsIn(selector).get('scroll-behavior')).toBeUndefined()
+  })
+
+  it('never makes the thread scroller smooth: its programmatic positioning must stay instant', () => {
+    expect(declarationsIn('.cv-p-thread__scroll').get('scroll-behavior')).toBeUndefined()
+    expect(declarationsIn('.cv-p-thread__scroll', mediaBody(NO_PREFERENCE)).get('scroll-behavior')).toBeUndefined()
+  })
+
+  it('has no scroll-behavior outside the no-preference block', () => {
+    const outside = PARTICIPANT_CSS.replace(mediaBody(NO_PREFERENCE) ?? '', '')
+    expect(outside).not.toMatch(/(?<!over)scroll-behavior/)
+  })
+})
+
+describe('scroll-to-latest button styles', () => {
+  const button = declarationsIn('.cv-p-thread__latest-button')
+
+  it('is a 44px touch target', () => {
+    expect(button.get('width')).toBe('var(--cv-p-i-touch)')
+    expect(button.get('height')).toBe('var(--cv-p-i-touch)')
+    expect(toRem(declarationsIn('.cv-p').get('--cv-p-i-touch'))).toBeGreaterThanOrEqual(2.75)
+  })
+
+  it('floats without taking room in the scroller', () => {
+    const anchor = declarationsIn('.cv-p-thread__latest')
+    expect(anchor.get('position')).toBe('sticky')
+    expect(anchor.get('bottom')).toBe('0')
+    expect(anchor.get('height')).toBe('0')
+    expect(button.get('position')).toBe('absolute')
+  })
+
+  it('animates its entrance only when motion is welcome', () => {
+    expect(declarationsIn('.cv-p-thread__latest-button', mediaBody(NO_PREFERENCE)).get('animation')).toContain(
+      'cv-p-latest-in',
+    )
+    expect(button.get('animation')).toBeUndefined()
+  })
+
+  it('outlines the badge under forced colors', () => {
+    expect(declarationsIn('.cv-p-thread__latest-badge', mediaBody(FORCED_COLORS)).get('border')).toContain('ButtonText')
+  })
+})
+
+describe('no leftovers', () => {
+  it('uses no Tailwind and no host vocabulary in the new rules', () => {
+    expect(PARTICIPANT_CSS).not.toMatch(/@apply|@tailwind/)
+  })
+})

package/src/participant/participantSubjectIcon.test.tsx

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'bun:test'
+
+import { buildConversation } from './participantFixtures.test-helper'
+import { resolveConversationIcon } from './participantSubjectIcon'
+
+const conversation = buildConversation({ subjectId: '1' })
+const group = { subjectType: 'invoice', label: 'Invoices', icon: <i>group</i> }
+
+describe('resolveConversationIcon', () => {
+  it('prefers the host icon, then the group icon, then nothing', () => {
+    const host = <b>host</b>
+    expect(resolveConversationIcon({ conversation, group, renderSubjectIcon: () => host })).toBe(host)
+    expect(resolveConversationIcon({ conversation, group })).toBe(group.icon)
+    expect(resolveConversationIcon({ conversation, group: { ...group, icon: undefined } })).toBeUndefined()
+    expect(resolveConversationIcon({ conversation, group: undefined })).toBeUndefined()
+  })
+
+  it.each([null, undefined, false, ''])('treats %p from the host as no icon, like the list row', (empty) => {
+    expect(resolveConversationIcon({ conversation, group, renderSubjectIcon: () => empty })).toBe(group.icon)
+  })
+
+  it('hands the conversation to the host renderer', () => {
+    const seen: string[] = []
+    resolveConversationIcon({ conversation, group, renderSubjectIcon: (item) => seen.push(item.subjectId) })
+    expect(seen).toEqual(['1'])
+  })
+})

package/src/participant/participantSubjectIcon.ts

@@ -0,0 +1,26 @@
+import type { ReactNode } from 'react'
+
+import type { ParticipantConversationSummary } from '@adatechnology/conversation-contracts'
+
+import type { ParticipantSubjectGroup, ParticipantSubjectIconRenderer } from './participant.types'
+
+export type ResolveConversationIconParams = {
+  readonly conversation: ParticipantConversationSummary
+  readonly group: ParticipantSubjectGroup | undefined
+  readonly renderSubjectIcon?: ParticipantSubjectIconRenderer
+}
+
+export function isDrawable(node: ReactNode): boolean {
+  return node !== null && node !== undefined && node !== false && node !== ''
+}
+
+/** Host icon, then group icon, then nothing; the list row adds its own text fallback, the header draws no tile. */
+export function resolveConversationIcon({
+  conversation,
+  group,
+  renderSubjectIcon,
+}: ResolveConversationIconParams): ReactNode | undefined {
+  const custom = renderSubjectIcon?.(conversation)
+  if (isDrawable(custom)) return custom
+  return isDrawable(group?.icon) ? group?.icon : undefined
+}

package/src/participant/useParticipantCopyFeedback.ts

@@ -0,0 +1,33 @@
+import { useEffect, useReducer } from 'react'
+
+import { useAnnounceCopy } from './ParticipantCopyAnnouncer'
+import { INITIAL_PROTOCOL_COPY_STATE, copyProtocolToClipboard, protocolCopyReducer } from './participantProtocolCopy'
+
+const COPIED_FEEDBACK_MS = 2000
+
+export type CopyFeedback = {
+  readonly isCopied: boolean
+  readonly copy: (value: string, announcement: string) => void
+}
+
+/** Copied state is local to each token; a clipboard failure is silent and shows nothing. */
+export function useParticipantCopyFeedback(): CopyFeedback {
+  const [state, dispatch] = useReducer(protocolCopyReducer, INITIAL_PROTOCOL_COPY_STATE)
+  const announce = useAnnounceCopy()
+  const { isCopied, copyCount } = state
+
+  useEffect(() => {
+    if (!isCopied) return undefined
+    const timer = setTimeout(() => dispatch({ type: 'expired' }), COPIED_FEEDBACK_MS)
+    return () => clearTimeout(timer)
+  }, [isCopied, copyCount])
+
+  async function copyValue(value: string, announcement: string): Promise<void> {
+    const clipboard = typeof navigator === 'undefined' ? undefined : navigator.clipboard
+    if (!(await copyProtocolToClipboard(value, clipboard))) return
+    dispatch({ type: 'copied' })
+    announce(announcement)
+  }
+
+  return { isCopied, copy: (value, announcement) => void copyValue(value, announcement) }
+}

package/src/participant/useParticipantThreadScroll.ts

@@ -2,6 +2,7 @@ import { useEffect, useRef } from 'react'
 
 import { collectServerMessageIds, countNewIncomingMessages } from './participantNewMessages'
 import type { ParticipantTimelineItem } from './participantMessages'
+import { useScrollAwayState } from './useScrollAwayState'
 import { useStickToBottom, type ParticipantThreadScroll } from './useStickToBottom'
 
 export type UseParticipantThreadScrollResult = {
@@ -14,8 +15,15 @@ function keyOf(item: ParticipantTimelineItem | undefined): string | undefined {
   return item.kind === 'server' ? item.message.id : `pending:${item.pending.clientMessageId}`
 }
 
-export function useParticipantThreadScroll(items: readonly ParticipantTimelineItem[]): UseParticipantThreadScrollResult {
-  const { scroll, isNearBottom } = useStickToBottom({ firstKey: keyOf(items[0]), lastKey: keyOf(items[items.length - 1]) })
+export function useParticipantThreadScroll(
+  items: readonly ParticipantTimelineItem[],
+): UseParticipantThreadScrollResult {
+  const { scroll: base, isNearBottom } = useStickToBottom({
+    firstKey: keyOf(items[0]),
+    lastKey: keyOf(items[items.length - 1]),
+  })
+  const { isAwayFromBottom, scrollToLatest } = useScrollAwayState(base.ref, isNearBottom)
+  const scroll = { ...base, isAwayFromBottom, scrollToLatest }
   const seenIds = useRef<ReadonlySet<string>>(new Set())
 
   useEffect(() => {

package/src/participant/useRevealActiveChip.ts

@@ -0,0 +1,20 @@
+import { useEffect, useRef, type RefObject } from 'react'
+
+import { readPrefersReducedMotion, scrollIntoViewOptions } from './participantScrollView'
+
+/** Brings the pressed chip into view when the active one changes; the first render never scrolls. */
+export function useRevealActiveChip(active: string): RefObject<HTMLDivElement | null> {
+  const strip = useRef<HTMLDivElement | null>(null)
+  const previousActive = useRef<string | undefined>(undefined)
+
+  useEffect(() => {
+    const wasActive = previousActive.current
+    previousActive.current = active
+    if (wasActive === undefined || wasActive === active) return
+    strip.current
+      ?.querySelector<HTMLElement>('[aria-pressed="true"]')
+      ?.scrollIntoView(scrollIntoViewOptions(readPrefersReducedMotion()))
+  }, [active])
+
+  return strip
+}

package/src/participant/useScrollAwayState.ts

@@ -0,0 +1,24 @@
+import { useCallback, type RefObject } from 'react'
+
+import { readPrefersReducedMotion, scrollToLatestOptions } from './participantScrollView'
+
+export type UseScrollAwayStateResult = {
+  readonly isAwayFromBottom: boolean
+  readonly scrollToLatest: () => void
+}
+
+/** Away is the negation of the near-the-end state useStickToBottom already tracks with shouldStickToBottom. */
+export function useScrollAwayState(
+  ref: RefObject<HTMLDivElement | null>,
+  isNearBottom: boolean,
+): UseScrollAwayStateResult {
+  const scrollToLatest = useCallback((): void => {
+    const element = ref.current
+    if (!element) return
+    element.scrollTo(
+      scrollToLatestOptions({ scrollHeight: element.scrollHeight, isReducedMotion: readPrefersReducedMotion() }),
+    )
+  }, [ref])
+
+  return { isAwayFromBottom: !isNearBottom, scrollToLatest }
+}