@adatechnology/conversations-ui 0.4.2 → 0.6.0

package/src/participant/participantLabels.ts

@@ -0,0 +1,115 @@
+export type ParticipantConversationsLabels = {
+  readonly inboxTitle: string
+  readonly sectionAwaiting: string
+  readonly sectionClosed: string
+  readonly sectionOther: string
+  readonly filterAll: string
+  readonly filtersGroup: string
+  readonly emptyInbox: string
+  /** Uses the `{count}` placeholder. */
+  readonly unreadCount: string
+  readonly back: string
+  readonly openSubject: string
+  readonly me: string
+  readonly newMessages: string
+  readonly loadOlder: string
+  readonly closedNotice: string
+  readonly messageInputLabel: string
+  readonly messageInputPlaceholder: string
+  readonly send: string
+  readonly attach: string
+  readonly attachmentsList: string
+  readonly removeAttachment: string
+  readonly attachmentTooLarge: string
+  readonly attachmentTypeNotAccepted: string
+  readonly quickRepliesGroup: string
+  readonly downloadAttachment: string
+  readonly statusSending: string
+  readonly statusQueued: string
+  readonly statusSent: string
+  readonly statusDelivered: string
+  readonly statusRead: string
+  readonly statusFailed: string
+  readonly statusFailedShort: string
+  readonly retry: string
+  readonly discard: string
+  readonly edit: string
+  readonly notFound: string
+  readonly loading: string
+  readonly loadError: string
+  readonly loadMore: string
+  readonly searchLabel: string
+  readonly searchPlaceholder: string
+  readonly noResults: string
+  readonly noResultsInFilter: string
+  readonly noResultsLoadedOnly: string
+  /** Spoken before the protocol code, e.g. "Protocol 261009-K7M2". */
+  readonly protocolPrefix: string
+  readonly copyProtocol: string
+  readonly protocolCopied: string
+  readonly channelsGroup: string
+  readonly channelApp: string
+  readonly channelWhatsapp: string
+  readonly channelEmail: string
+  readonly channelPortal: string
+  readonly channelWebchat: string
+}
+
+export const DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS: ParticipantConversationsLabels = {
+  inboxTitle: 'Conversations',
+  sectionAwaiting: 'Waiting for your reply',
+  sectionClosed: 'Closed',
+  sectionOther: 'Other',
+  filterAll: 'All',
+  filtersGroup: 'Filter by subject',
+  emptyInbox: 'No conversations yet',
+  unreadCount: '{count} unread',
+  back: 'Back',
+  openSubject: 'Open subject',
+  me: 'Me',
+  newMessages: 'New messages',
+  loadOlder: 'Load older messages',
+  closedNotice: 'This conversation is closed',
+  messageInputLabel: 'Message',
+  messageInputPlaceholder: 'Write a message…',
+  send: 'Send',
+  attach: 'Attach',
+  attachmentsList: 'Selected attachments',
+  removeAttachment: 'Remove attachment',
+  attachmentTooLarge: 'Attachment too large',
+  attachmentTypeNotAccepted: 'File type not accepted',
+  quickRepliesGroup: 'Quick replies',
+  downloadAttachment: 'Download',
+  statusSending: 'Sending',
+  statusQueued: 'Queued — sends when back online',
+  statusSent: 'Sent',
+  statusDelivered: 'Delivered',
+  statusRead: 'Read',
+  statusFailed: 'Failed — tap to retry',
+  statusFailedShort: 'Failed',
+  retry: 'Retry',
+  discard: 'Discard',
+  edit: 'Edit',
+  notFound: 'Conversation not found',
+  loading: 'Loading…',
+  loadError: 'Could not load. Check your connection and try again.',
+  loadMore: 'Load more',
+  searchLabel: 'Search conversations',
+  searchPlaceholder: 'Search by title or protocol',
+  noResults: 'No conversations found',
+  noResultsInFilter: 'No results in this filter — try All',
+  noResultsLoadedOnly: 'Nothing in the loaded conversations — load more',
+  protocolPrefix: 'Protocol',
+  copyProtocol: 'Copy protocol',
+  protocolCopied: 'Protocol copied',
+  channelsGroup: 'Channels in this conversation',
+  channelApp: 'App',
+  channelWhatsapp: 'WhatsApp',
+  channelEmail: 'Email',
+  channelPortal: 'Portal',
+  channelWebchat: 'Web chat',
+}
+
+export function formatParticipantLabel(template: string, count: number): string {
+  return template.replace('{count}', String(count))
+}

package/src/participant/participantLoadView.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'bun:test'
+
+import { resolveLoadView } from './participantLoadView'
+
+describe('resolveLoadView', () => {
+  it('is loading while idle or loading with nothing to show', () => {
+    expect(resolveLoadView({ status: 'idle', hasItems: false })).toEqual({ isLoading: true, hasError: false, isEmpty: false })
+    expect(resolveLoadView({ status: 'loading', hasItems: false })).toEqual({ isLoading: true, hasError: false, isEmpty: false })
+  })
+
+  it('keeps showing items while revalidating', () => {
+    expect(resolveLoadView({ status: 'loading', hasItems: true })).toEqual({ isLoading: false, hasError: false, isEmpty: false })
+  })
+
+  it('is empty only after a successful load', () => {
+    expect(resolveLoadView({ status: 'ready', hasItems: false })).toEqual({ isLoading: false, hasError: false, isEmpty: true })
+    expect(resolveLoadView({ status: 'error', hasItems: false })).toEqual({ isLoading: false, hasError: true, isEmpty: false })
+  })
+
+  it('reports the error even when items remain on screen', () => {
+    expect(resolveLoadView({ status: 'error', hasItems: true }).hasError).toBe(true)
+  })
+})

package/src/participant/participantLoadView.ts

@@ -0,0 +1,21 @@
+export type ParticipantLoadStatus = 'idle' | 'loading' | 'ready' | 'error'
+
+export type ResolveLoadViewParams = {
+  readonly status: ParticipantLoadStatus
+  readonly hasItems: boolean
+}
+
+export type ParticipantLoadView = {
+  readonly isLoading: boolean
+  readonly hasError: boolean
+  /** Only after a successful load: an error or a pending load never draws the empty state. */
+  readonly isEmpty: boolean
+}
+
+export function resolveLoadView({ status, hasItems }: ResolveLoadViewParams): ParticipantLoadView {
+  return {
+    isLoading: (status === 'idle' || status === 'loading') && !hasItems,
+    hasError: status === 'error',
+    isEmpty: status === 'ready' && !hasItems,
+  }
+}

package/src/participant/participantMessages.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it } from 'bun:test'
+
+import type { ParticipantMessage } from '@adatechnology/conversation-contracts'
+
+import type { ParticipantLocalPendingMessage, ParticipantPendingMessage } from './participantApi.types'
+import { isOwnMessage, mergeParticipantMessages, resolveOwnMessageStatus } from './participantMessages'
+
+const SUBJECT = { subjectType: 'trip', subjectId: 'a' }
+const OTHER_SUBJECT = { subjectType: 'trip', subjectId: 'b' }
+
+function server(id: string, createdAt: string, overrides: Partial<ParticipantMessage> = {}): ParticipantMessage {
+  return { id, direction: 'inbound', attachments: [], createdAt, ...overrides }
+}
+function host(clientMessageId: string, createdAt: string, overrides: Partial<ParticipantPendingMessage> = {}): ParticipantPendingMessage {
+  return { clientMessageId, subject: SUBJECT, text: 'x', createdAt, state: 'queued', ...overrides }
+}
+function local(clientMessageId: string, createdAt: string, overrides: Partial<ParticipantLocalPendingMessage> = {}): ParticipantLocalPendingMessage {
+  return { clientMessageId, subject: SUBJECT, text: 'x', createdAt, state: 'sending', ...overrides }
+}
+
+describe('mergeParticipantMessages', () => {
+  it('orders everything by createdAt ascending', () => {
+    const items = mergeParticipantMessages({
+      serverMessages: [server('s2', '2026-10-01T10:02:00.000Z'), server('s1', '2026-10-01T10:00:00.000Z')],
+      hostPending: [host('h1', '2026-10-01T10:03:00.000Z')],
+      localPending: [local('l1', '2026-10-01T10:01:00.000Z')],
+      subject: SUBJECT,
+    })
+    expect(items.map((item) => (item.kind === 'server' ? item.message.id : item.pending.clientMessageId))).toEqual(['s1', 'l1', 's2', 'h1'])
+  })
+
+  it('hides a host pending when a server message has the same clientMessageId', () => {
+    const items = mergeParticipantMessages({
+      serverMessages: [server('s1', '2026-10-01T10:00:00.000Z', { clientMessageId: 'c1' })],
+      hostPending: [host('c1', '2026-10-01T09:59:00.000Z')],
+      localPending: [],
+      subject: SUBJECT,
+    })
+    expect(items).toHaveLength(1)
+    expect(items[0]?.kind).toBe('server')
+  })
+
+  it('ignores host pending of another subject', () => {
+    const items = mergeParticipantMessages({
+      serverMessages: [],
+      hostPending: [host('c1', '2026-10-01T09:59:00.000Z', { subject: OTHER_SUBJECT })],
+      localPending: [],
+      subject: SUBJECT,
+    })
+    expect(items).toHaveLength(0)
+  })
+
+  it('maps host pending states and tags the origin', () => {
+    const items = mergeParticipantMessages({
+      serverMessages: [],
+      hostPending: [host('q', '2026-10-01T10:00:00.000Z'), host('f', '2026-10-01T10:01:00.000Z', { state: 'failed' })],
+      localPending: [],
+      subject: SUBJECT,
+    })
+    expect(items.map((item) => (item.kind === 'pending' ? [item.origin, item.displayState] : []))).toEqual([
+      ['host', 'queued'],
+      ['host', 'failed'],
+    ])
+  })
+
+  it('shows local pending as sending or failed when no other source has it', () => {
+    const items = mergeParticipantMessages({
+      serverMessages: [],
+      hostPending: [],
+      localPending: [local('a', '2026-10-01T10:00:00.000Z'), local('b', '2026-10-01T10:01:00.000Z', { state: 'failed' })],
+      subject: SUBJECT,
+    })
+    expect(items.map((item) => (item.kind === 'pending' ? [item.origin, item.displayState] : []))).toEqual([
+      ['local', 'sending'],
+      ['local', 'failed'],
+    ])
+  })
+
+  it('hides a local pending already present on the server or at the host', () => {
+    const items = mergeParticipantMessages({
+      serverMessages: [server('s1', '2026-10-01T10:00:00.000Z', { clientMessageId: 'a' })],
+      hostPending: [host('b', '2026-10-01T10:01:00.000Z')],
+      localPending: [local('a', '2026-10-01T09:59:00.000Z'), local('b', '2026-10-01T09:59:30.000Z')],
+      subject: SUBJECT,
+    })
+    expect(items.map((item) => item.kind)).toEqual(['server', 'pending'])
+    expect(items[1]).toMatchObject({ kind: 'pending', origin: 'host' })
+  })
+
+  it('keeps a failed local pending with its original clientMessageId for resend', () => {
+    const items = mergeParticipantMessages({
+      serverMessages: [],
+      hostPending: [],
+      localPending: [local('keep-me', '2026-10-01T10:00:00.000Z', { state: 'failed' })],
+      subject: SUBJECT,
+    })
+    expect(items[0]).toMatchObject({ kind: 'pending', pending: { clientMessageId: 'keep-me' } })
+  })
+})
+
+describe('isOwnMessage', () => {
+  it('treats inbound (company perspective) as the participant own message', () => {
+    expect(isOwnMessage(server('s', '2026-10-01T10:00:00.000Z', { direction: 'inbound' }))).toBe(true)
+    expect(isOwnMessage(server('s', '2026-10-01T10:00:00.000Z', { direction: 'outbound' }))).toBe(false)
+  })
+})
+
+describe('resolveOwnMessageStatus', () => {
+  it('uses the local display state for pending messages', () => {
+    expect(resolveOwnMessageStatus({ displayState: 'sending', confirmsRead: true })).toBe('sending')
+    expect(resolveOwnMessageStatus({ displayState: 'queued', confirmsRead: true })).toBe('queued')
+    expect(resolveOwnMessageStatus({ displayState: 'failed', confirmsRead: true })).toBe('failed')
+  })
+  it('defaults to sent without server status', () => {
+    expect(resolveOwnMessageStatus({ confirmsRead: true })).toBe('sent')
+  })
+  it('maps server statuses', () => {
+    expect(resolveOwnMessageStatus({ serverStatus: 'queued', confirmsRead: true })).toBe('queued')
+    expect(resolveOwnMessageStatus({ serverStatus: 'sent', confirmsRead: true })).toBe('sent')
+    expect(resolveOwnMessageStatus({ serverStatus: 'delivered', confirmsRead: true })).toBe('delivered')
+    expect(resolveOwnMessageStatus({ serverStatus: 'failed', confirmsRead: true })).toBe('failed')
+    expect(resolveOwnMessageStatus({ serverStatus: 'bounced', confirmsRead: true })).toBe('failed')
+  })
+  it('reports read only when the channel confirms it', () => {
+    expect(resolveOwnMessageStatus({ serverStatus: 'read', confirmsRead: true })).toBe('read')
+    expect(resolveOwnMessageStatus({ serverStatus: 'read', confirmsRead: false })).toBe('delivered')
+  })
+})

package/src/participant/participantMessages.ts

@@ -0,0 +1,73 @@
+import type { MessageDeliveryStatus, ParticipantMessage, ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+import type { ParticipantLocalPendingMessage, ParticipantPendingMessage } from './participantApi.types'
+
+export type ParticipantPendingDisplayState = 'sending' | 'queued' | 'failed' | 'sent'
+export type ParticipantOwnMessageStatus = 'sending' | 'queued' | 'sent' | 'delivered' | 'read' | 'failed'
+
+export type ParticipantTimelineItem =
+  | { readonly kind: 'server'; readonly message: ParticipantMessage }
+  | {
+      readonly kind: 'pending'
+      readonly pending: ParticipantPendingMessage | ParticipantLocalPendingMessage
+      readonly origin: 'host' | 'local'
+      readonly displayState: ParticipantPendingDisplayState
+    }
+
+export type MergeParticipantMessagesParams = {
+  readonly serverMessages: readonly ParticipantMessage[]
+  readonly hostPending: readonly ParticipantPendingMessage[]
+  readonly localPending: readonly ParticipantLocalPendingMessage[]
+  readonly subject: ParticipantSubjectRef
+}
+
+export type ResolveOwnMessageStatusParams = {
+  readonly displayState?: ParticipantPendingDisplayState
+  readonly serverStatus?: MessageDeliveryStatus
+  readonly confirmsRead: boolean
+}
+
+function isSameSubject(left: ParticipantSubjectRef, right: ParticipantSubjectRef): boolean {
+  return left.subjectType === right.subjectType && left.subjectId === right.subjectId
+}
+
+function createdAtOf(item: ParticipantTimelineItem): number {
+  return Date.parse(item.kind === 'server' ? item.message.createdAt : item.pending.createdAt)
+}
+
+export function mergeParticipantMessages(params: MergeParticipantMessagesParams): readonly ParticipantTimelineItem[] {
+  const { serverMessages, hostPending, localPending, subject } = params
+  const knownClientIds = new Set<string>()
+  for (const message of serverMessages) {
+    if (message.clientMessageId) knownClientIds.add(message.clientMessageId)
+  }
+
+  const items: ParticipantTimelineItem[] = serverMessages.map((message) => ({ kind: 'server', message }))
+
+  for (const pending of hostPending) {
+    if (!isSameSubject(pending.subject, subject) || knownClientIds.has(pending.clientMessageId)) continue
+    knownClientIds.add(pending.clientMessageId)
+    items.push({ kind: 'pending', pending, origin: 'host', displayState: pending.state })
+  }
+
+  for (const pending of localPending) {
+    if (!isSameSubject(pending.subject, subject) || knownClientIds.has(pending.clientMessageId)) continue
+    items.push({ kind: 'pending', pending, origin: 'local', displayState: pending.state })
+  }
+
+  return items.sort((left, right) => createdAtOf(left) - createdAtOf(right))
+}
+
+/** Direction is from the company perspective: the participant is the inbound side. */
+export function isOwnMessage(message: ParticipantMessage): boolean {
+  return message.direction === 'inbound'
+}
+
+export function resolveOwnMessageStatus(params: ResolveOwnMessageStatusParams): ParticipantOwnMessageStatus {
+  const { displayState, serverStatus, confirmsRead } = params
+  if (displayState) return displayState
+  if (serverStatus === undefined) return 'sent'
+  if (serverStatus === 'failed' || serverStatus === 'bounced') return 'failed'
+  if (serverStatus === 'read') return confirmsRead ? 'read' : 'delivered'
+  return serverStatus
+}

package/src/participant/participantNewMessages.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'bun:test'
+
+import { buildMessage } from './participantFixtures.test-helper'
+import { collectServerMessageIds, countNewIncomingMessages } from './participantNewMessages'
+import type { ParticipantTimelineItem } from './participantMessages'
+
+function server(id: string, direction: 'inbound' | 'outbound', createdAt = '2026-10-01T10:00:00.000Z'): ParticipantTimelineItem {
+  return { kind: 'server', message: buildMessage({ id, direction, createdAt }) }
+}
+
+describe('countNewIncomingMessages', () => {
+  it('counts only unseen messages from the other side (outbound)', () => {
+    const items = [
+      server('a', 'outbound', '2026-10-01T10:00:00.000Z'),
+      server('b', 'outbound', '2026-10-01T10:01:00.000Z'),
+      server('c', 'inbound', '2026-10-01T10:02:00.000Z'),
+      server('d', 'outbound', '2026-10-01T10:03:00.000Z'),
+    ]
+    expect(countNewIncomingMessages(new Set(['a']), items)).toBe(2)
+  })
+
+  it('does not count outbound history loaded above the messages already seen', () => {
+    const seen = [server('m30', 'outbound', '2026-10-01T10:30:00.000Z'), server('m31', 'inbound', '2026-10-01T10:31:00.000Z')]
+    const older = [server('m1', 'outbound', '2026-10-01T10:01:00.000Z'), server('m2', 'outbound', '2026-10-01T10:02:00.000Z')]
+    expect(countNewIncomingMessages(collectServerMessageIds(seen), [...older, ...seen])).toBe(0)
+  })
+
+  it('counts a reply that arrives after the messages already seen', () => {
+    const seen = [server('m30', 'outbound', '2026-10-01T10:30:00.000Z'), server('m31', 'inbound', '2026-10-01T10:31:00.000Z')]
+    const reply = server('m32', 'outbound', '2026-10-01T10:32:00.000Z')
+    expect(countNewIncomingMessages(collectServerMessageIds(seen), [...seen, reply])).toBe(1)
+  })
+
+  it('is zero when everything was seen', () => {
+    const items = [server('a', 'outbound')]
+    expect(countNewIncomingMessages(collectServerMessageIds(items), items)).toBe(0)
+  })
+
+  it('ignores the pending messages of the participant', () => {
+    const pending: ParticipantTimelineItem = {
+      kind: 'pending',
+      origin: 'local',
+      displayState: 'sending',
+      pending: { clientMessageId: 'x', subject: { subjectType: 'invoice', subjectId: '1' }, createdAt: '2026-10-01T10:00:00.000Z', state: 'sending', text: 'hi' },
+    }
+    expect(countNewIncomingMessages(new Set(), [pending])).toBe(0)
+  })
+})
+
+describe('collectServerMessageIds', () => {
+  it('collects the ids of server items only', () => {
+    expect([...collectServerMessageIds([server('a', 'inbound'), server('b', 'outbound')])]).toEqual(['a', 'b'])
+  })
+})

package/src/participant/participantNewMessages.ts

@@ -0,0 +1,29 @@
+import type { ParticipantTimelineItem } from './participantMessages'
+
+export function collectServerMessageIds(items: readonly ParticipantTimelineItem[]): ReadonlySet<string> {
+  const ids = new Set<string>()
+  for (const item of items) {
+    if (item.kind === 'server') ids.add(item.message.id)
+  }
+  return ids
+}
+
+function latestSeenTime(previousIds: ReadonlySet<string>, items: readonly ParticipantTimelineItem[]): number {
+  let latest = Number.NEGATIVE_INFINITY
+  for (const item of items) {
+    if (item.kind === 'server' && previousIds.has(item.message.id)) latest = Math.max(latest, Date.parse(item.message.createdAt))
+  }
+  return latest
+}
+
+/** Messages from the other side ('outbound') newer than what the participant has seen; older history loaded above is not news. */
+export function countNewIncomingMessages(previousIds: ReadonlySet<string>, currentItems: readonly ParticipantTimelineItem[]): number {
+  const latestSeen = latestSeenTime(previousIds, currentItems)
+  return currentItems.filter(
+    (item) =>
+      item.kind === 'server' &&
+      item.message.direction === 'outbound' &&
+      !previousIds.has(item.message.id) &&
+      Date.parse(item.message.createdAt) > latestSeen,
+  ).length
+}

package/src/participant/participantProtocol.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'bun:test'
+
+import { buildConversation } from './participantFixtures.test-helper'
+import {
+  PROTOCOL_SEARCH_CONVERSATION_THRESHOLD,
+  filterConversationsBySearch,
+  isInboxSearchVisible,
+  matchesProtocolQuery,
+  normalizeProtocolQuery,
+  shouldShowInboxSearch,
+} from './participantProtocol'
+
+describe('normalizeProtocolQuery', () => {
+  it('uppercases and drops dashes and spaces', () => {
+    expect(normalizeProtocolQuery(' 261009-k7 m2 ')).toBe('261009K7M2')
+  })
+})
+
+describe('matchesProtocolQuery', () => {
+  it('matches partially, without dash and without case', () => {
+    expect(matchesProtocolQuery('261009-K7M2', '261009k7')).toBe(true)
+    expect(matchesProtocolQuery('261009-K7M2', 'k7m2')).toBe(true)
+    expect(matchesProtocolQuery('261009-K7M2', '9-k')).toBe(true)
+  })
+
+  it('does not match a different code', () => {
+    expect(matchesProtocolQuery('261009-K7M2', 'ZZZ')).toBe(false)
+  })
+
+  it('an empty query matches everything, even a missing protocol', () => {
+    expect(matchesProtocolQuery(undefined, '')).toBe(true)
+    expect(matchesProtocolQuery('261009-K7M2', '  ')).toBe(true)
+  })
+
+  it('a missing protocol never matches a real query', () => {
+    expect(matchesProtocolQuery(undefined, 'K7')).toBe(false)
+  })
+})
+
+describe('filterConversationsBySearch', () => {
+  const conversations = [
+    buildConversation({ subjectId: '1', subjectLabel: 'Damaged item', protocol: '261009-K7M2' }),
+    buildConversation({ subjectId: '2', subjectLabel: 'Late item' }),
+    buildConversation({ subjectId: '3', subjectLabel: 'Other topic', protocol: '261008-AB23' }),
+  ]
+  const ids = (query: string) => filterConversationsBySearch(conversations, query).map((item) => item.subjectId)
+
+  it('returns everything for an empty query', () => {
+    expect(ids('')).toEqual(['1', '2', '3'])
+    expect(ids('   ')).toEqual(['1', '2', '3'])
+  })
+
+  it('matches the title without accent or case', () => {
+    expect(ids('DAMAGED')).toEqual(['1'])
+    expect(ids('látè')).toEqual(['2'])
+  })
+
+  it('matches the protocol partially, without dash and case', () => {
+    expect(ids('k7m')).toEqual(['1'])
+    expect(ids('261008')).toEqual(['3'])
+    expect(ids('2610')).toEqual(['1', '3'])
+  })
+
+  it('a query of only separators does not match every protocol', () => {
+    expect(ids('-')).toEqual([])
+  })
+
+  it('returns nothing when neither title nor protocol match', () => {
+    expect(ids('zzz')).toEqual([])
+  })
+})
+
+describe('shouldShowInboxSearch', () => {
+  it('shows when some conversation has a protocol', () => {
+    expect(shouldShowInboxSearch([buildConversation({ subjectId: '1', protocol: '261009-K7M2' })])).toBe(true)
+  })
+
+  it('shows beyond the threshold even without protocols', () => {
+    const many = Array.from({ length: PROTOCOL_SEARCH_CONVERSATION_THRESHOLD + 1 }, (_, index) =>
+      buildConversation({ subjectId: String(index) }),
+    )
+    expect(shouldShowInboxSearch(many)).toBe(true)
+    expect(shouldShowInboxSearch(many.slice(0, PROTOCOL_SEARCH_CONVERSATION_THRESHOLD))).toBe(false)
+  })
+
+  it('hides for a short list without protocols', () => {
+    expect(shouldShowInboxSearch([buildConversation({ subjectId: '1' })])).toBe(false)
+  })
+})
+
+describe('isInboxSearchVisible', () => {
+  const short = [buildConversation({ subjectId: '1' })]
+  const withProtocol = [buildConversation({ subjectId: '1', protocol: '261009-K7M2' })]
+
+  it('follows the threshold rule when there is no query', () => {
+    expect(isInboxSearchVisible({ conversations: short, searchQuery: '' })).toBe(false)
+    expect(isInboxSearchVisible({ conversations: withProtocol, searchQuery: '' })).toBe(true)
+  })
+
+  it('stays visible while a query is applied, even if a refresh shrank the list', () => {
+    expect(isInboxSearchVisible({ conversations: short, searchQuery: 'k7' })).toBe(true)
+    expect(isInboxSearchVisible({ conversations: [], searchQuery: 'k7' })).toBe(true)
+  })
+})

package/src/participant/participantProtocol.ts

@@ -0,0 +1,52 @@
+import type { ParticipantConversationSummary } from '@adatechnology/conversation-contracts'
+
+/** Search appears when the list is long even if no conversation carries a protocol. */
+export const PROTOCOL_SEARCH_CONVERSATION_THRESHOLD = 8
+
+export function normalizeProtocolQuery(text: string): string {
+  return text.replace(/[-\s]/g, '').toUpperCase()
+}
+
+export function matchesProtocolQuery(protocol: string | undefined, query: string): boolean {
+  const normalizedQuery = normalizeProtocolQuery(query)
+  if (normalizedQuery === '') return true
+  if (protocol === undefined) return false
+  return normalizeProtocolQuery(protocol).includes(normalizedQuery)
+}
+
+function foldText(text: string): string {
+  return text.normalize('NFD').replace(/\p{M}/gu, '').toLowerCase()
+}
+
+function matchesTitle(subjectLabel: string, query: string): boolean {
+  return foldText(subjectLabel).includes(foldText(query))
+}
+
+export function filterConversationsBySearch(
+  conversations: readonly ParticipantConversationSummary[],
+  query: string,
+): readonly ParticipantConversationSummary[] {
+  const trimmedQuery = query.trim()
+  if (trimmedQuery === '') return conversations
+  const hasProtocolTerm = normalizeProtocolQuery(trimmedQuery) !== ''
+  return conversations.filter(
+    (conversation) =>
+      matchesTitle(conversation.subjectLabel, trimmedQuery) ||
+      (hasProtocolTerm && matchesProtocolQuery(conversation.protocol, trimmedQuery)),
+  )
+}
+
+export type InboxSearchVisibilityParams = {
+  readonly conversations: readonly ParticipantConversationSummary[]
+  readonly searchQuery: string
+}
+
+/** An applied query keeps the field, so a refresh that shrinks the list cannot strand it. */
+export function isInboxSearchVisible({ conversations, searchQuery }: InboxSearchVisibilityParams): boolean {
+  return searchQuery !== '' || shouldShowInboxSearch(conversations)
+}
+
+export function shouldShowInboxSearch(conversations: readonly ParticipantConversationSummary[]): boolean {
+  if (conversations.length > PROTOCOL_SEARCH_CONVERSATION_THRESHOLD) return true
+  return conversations.some((conversation) => conversation.protocol !== undefined)
+}

package/src/participant/participantProtocolCopy.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'bun:test'
+
+import { INITIAL_PROTOCOL_COPY_STATE, copyProtocolToClipboard, protocolCopyReducer } from './participantProtocolCopy'
+
+describe('copyProtocolToClipboard', () => {
+  it('writes the protocol and reports success', async () => {
+    const written: string[] = []
+    const clipboard = { writeText: async (text: string) => void written.push(text) }
+    expect(await copyProtocolToClipboard('261009-K7M2', clipboard)).toBe(true)
+    expect(written).toEqual(['261009-K7M2'])
+  })
+
+  it('reports failure silently when the clipboard rejects', async () => {
+    const clipboard = { writeText: async () => Promise.reject(new Error('denied')) }
+    expect(await copyProtocolToClipboard('261009-K7M2', clipboard)).toBe(false)
+  })
+
+  it('reports failure when there is no clipboard', async () => {
+    expect(await copyProtocolToClipboard('261009-K7M2', undefined)).toBe(false)
+  })
+})
+
+describe('protocolCopyReducer', () => {
+  it('starts not copied', () => {
+    expect(INITIAL_PROTOCOL_COPY_STATE).toEqual({ copyCount: 0, isCopied: false })
+  })
+
+  it('a copy marks it copied and counts it', () => {
+    expect(protocolCopyReducer(INITIAL_PROTOCOL_COPY_STATE, { type: 'copied' })).toEqual({
+      copyCount: 1,
+      isCopied: true,
+    })
+  })
+
+  it('a second copy while still copied bumps the counter so the timer restarts and the notice is announced again', () => {
+    const first = protocolCopyReducer(INITIAL_PROTOCOL_COPY_STATE, { type: 'copied' })
+    const second = protocolCopyReducer(first, { type: 'copied' })
+    expect(second).toEqual({ copyCount: 2, isCopied: true })
+  })
+
+  it('expiry clears the notice and keeps the count', () => {
+    const copied = protocolCopyReducer(INITIAL_PROTOCOL_COPY_STATE, { type: 'copied' })
+    expect(protocolCopyReducer(copied, { type: 'expired' })).toEqual({ copyCount: 1, isCopied: false })
+  })
+})