@adatechnology/conversations-ui 0.4.1 → 0.5.0

package/src/participant/participantFileValidation.ts

@@ -0,0 +1,72 @@
+import { channelCapabilityFor } from '../channelCapability'
+import type { ConversationChannel } from '../conversationChannel'
+
+export type ParticipantFileRejection = 'tooLarge' | 'typeNotAccepted'
+
+export type ValidateParticipantFilesParams = {
+  readonly files: readonly File[]
+  readonly maxBytes: number
+  /** MIME types or wildcards such as `image/*`. Absent means any type. */
+  readonly acceptedTypes?: readonly string[]
+}
+
+export type ValidateParticipantFilesResult = {
+  readonly accepted: readonly File[]
+  readonly rejection?: ParticipantFileRejection
+}
+
+function matchesAcceptedType(mimeType: string, acceptedTypes: readonly string[]): boolean {
+  return acceptedTypes.some((accepted) =>
+    accepted.endsWith('/*') ? mimeType.startsWith(accepted.slice(0, -1)) : mimeType === accepted,
+  )
+}
+
+function rejectionOf(file: File, params: Omit<ValidateParticipantFilesParams, 'files'>): ParticipantFileRejection | undefined {
+  if (params.acceptedTypes && !matchesAcceptedType(file.type, params.acceptedTypes)) return 'typeNotAccepted'
+  if (file.size > params.maxBytes) return 'tooLarge'
+  return undefined
+}
+
+export function validateParticipantFiles(params: ValidateParticipantFilesParams): ValidateParticipantFilesResult {
+  const accepted: File[] = []
+  let rejection: ParticipantFileRejection | undefined
+  for (const file of params.files) {
+    const reason = rejectionOf(file, params)
+    if (reason === undefined) accepted.push(file)
+    else rejection = rejection ?? reason
+  }
+  return rejection === undefined ? { accepted } : { accepted, rejection }
+}
+
+export type RejectedParticipantFile = {
+  readonly file: File
+  readonly reason: ParticipantFileRejection
+}
+
+export type ReduceFilesSelectionParams = {
+  readonly current: readonly File[]
+  readonly incoming: readonly File[]
+  readonly maxBytes: number
+  readonly acceptedTypes?: readonly string[]
+}
+
+export type ReduceFilesSelectionResult = {
+  readonly files: readonly File[]
+  readonly rejected: readonly RejectedParticipantFile[]
+}
+
+/** A refusal never drops what was already chosen: valid files are kept, refused ones are reported. */
+export function reduceFilesSelection(params: ReduceFilesSelectionParams): ReduceFilesSelectionResult {
+  const files = [...params.current]
+  const rejected: RejectedParticipantFile[] = []
+  for (const file of params.incoming) {
+    const reason = rejectionOf(file, params)
+    if (reason === undefined) files.push(file)
+    else rejected.push({ file, reason })
+  }
+  return { files, rejected }
+}
+
+export function maxBytesForChannel(channel: ConversationChannel = 'app'): number {
+  return channelCapabilityFor(channel).attachments.maxBytes
+}

package/src/participant/participantFixtures.test-helper.ts

@@ -0,0 +1,41 @@
+import type { ParticipantConversationSummary, ParticipantMessage } from '@adatechnology/conversation-contracts'
+
+export function buildConversation(
+  overrides: Partial<ParticipantConversationSummary> & { subjectId: string },
+): ParticipantConversationSummary {
+  return {
+    subjectType: 'invoice',
+    subjectLabel: 'Invoice 4521',
+    lastMessageAt: '2026-10-01T10:00:00.000Z',
+    unreadCount: 0,
+    awaitingParticipant: false,
+    status: 'open',
+    ...overrides,
+  }
+}
+
+export function buildMessage(overrides: Partial<ParticipantMessage> & { id: string }): ParticipantMessage {
+  return {
+    direction: 'outbound',
+    text: 'Hello',
+    attachments: [],
+    createdAt: '2026-10-01T10:00:00.000Z',
+    ...overrides,
+  }
+}
+
+const UTILITY_PREFIXES = /^(flex|grid|block|inline|hidden|p[xytblr]?-|m[xytblr]?-|text-|bg-|border|rounded|w-|h-|min-|max-|items-|justify-|gap-|space-|font-|shadow|dark:|hover:|sm:|md:)/
+
+/** Returns the class tokens in the markup that look like Tailwind utilities. */
+export function findUtilityClassTokens(markup: string): string[] {
+  const classAttributes = [...markup.matchAll(/class="([^"]*)"/g)].map((match) => match[1] ?? '')
+  const tokens = classAttributes.flatMap((value) => value.split(/\s+/).filter(Boolean))
+  return tokens.filter((token) => UTILITY_PREFIXES.test(token))
+}
+
+/** Returns class tokens that do not belong to the participant namespace or the reused leaf components. */
+export function findForeignClassTokens(markup: string): string[] {
+  const classAttributes = [...markup.matchAll(/class="([^"]*)"/g)].map((match) => match[1] ?? '')
+  const tokens = classAttributes.flatMap((value) => value.split(/\s+/).filter(Boolean))
+  return tokens.filter((token) => !/^(cv-p$|cv-p-|cv-status-ticks|cv-message-text|lucide)/.test(token))
+}

package/src/participant/participantGrouping.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from 'bun:test'
+
+import type { ParticipantConversationSummary } from '@adatechnology/conversation-contracts'
+
+import { groupParticipantConversations } from './participantGrouping'
+
+function build(overrides: Partial<ParticipantConversationSummary> & { subjectId: string }): ParticipantConversationSummary {
+  return {
+    subjectType: 'invoice',
+    subjectLabel: 'Label',
+    lastMessageAt: '2026-10-01T10:00:00.000Z',
+    unreadCount: 0,
+    awaitingParticipant: false,
+    status: 'open',
+    ...overrides,
+  }
+}
+
+const GROUPS = [
+  { subjectType: 'zeta', label: 'Zeta' },
+  { subjectType: 'alpha', label: 'Alpha' },
+] as const
+
+function keysOf(view: ReturnType<typeof groupParticipantConversations>): string[] {
+  return view.sections.map((section) => section.key)
+}
+
+describe('groupParticipantConversations', () => {
+  it('applies precedence closed > awaiting > group > other', () => {
+    const view = groupParticipantConversations({
+      subjectGroups: GROUPS,
+      conversations: [
+        build({ subjectId: '1', subjectType: 'zeta', status: 'closed', awaitingParticipant: true }),
+        build({ subjectId: '2', subjectType: 'zeta', awaitingParticipant: true }),
+        build({ subjectId: '3', subjectType: 'zeta' }),
+        build({ subjectId: '4', subjectType: 'unknown' }),
+      ],
+    })
+    expect(keysOf(view)).toEqual(['awaiting', 'zeta', 'other', 'closed'])
+    expect(view.sections.map((section) => section.conversations.map((c) => c.subjectId))).toEqual([
+      ['2'],
+      ['3'],
+      ['4'],
+      ['1'],
+    ])
+  })
+
+  it('orders group sections by the subjectGroups array, not alphabetically, skipping empty groups', () => {
+    const view = groupParticipantConversations({
+      subjectGroups: [...GROUPS, { subjectType: 'empty', label: 'Empty' }],
+      conversations: [build({ subjectId: '1', subjectType: 'alpha' }), build({ subjectId: '2', subjectType: 'zeta' })],
+    })
+    expect(keysOf(view)).toEqual(['zeta', 'alpha'])
+  })
+
+  it('sorts by lastMessageAt descending, null last, ties by subjectLabel', () => {
+    const view = groupParticipantConversations({
+      subjectGroups: GROUPS,
+      conversations: [
+        build({ subjectId: 'a', subjectType: 'zeta', lastMessageAt: null, subjectLabel: 'A' }),
+        build({ subjectId: 'b', subjectType: 'zeta', lastMessageAt: '2026-10-01T10:00:00.000Z', subjectLabel: 'Beta' }),
+        build({ subjectId: 'c', subjectType: 'zeta', lastMessageAt: '2026-10-02T10:00:00.000Z', subjectLabel: 'Z' }),
+        build({ subjectId: 'd', subjectType: 'zeta', lastMessageAt: '2026-10-01T10:00:00.000Z', subjectLabel: 'Alpha' }),
+      ],
+    })
+    expect(view.sections[0]?.conversations.map((c) => c.subjectId)).toEqual(['c', 'd', 'b', 'a'])
+  })
+
+  it('sums unread per section and per filter', () => {
+    const view = groupParticipantConversations({
+      subjectGroups: GROUPS,
+      conversations: [
+        build({ subjectId: '1', subjectType: 'zeta', unreadCount: 2 }),
+        build({ subjectId: '2', subjectType: 'zeta', unreadCount: 3, awaitingParticipant: true }),
+        build({ subjectId: '3', subjectType: 'alpha', unreadCount: 4 }),
+      ],
+    })
+    expect(view.sections.map((section) => [section.key, section.unreadCount])).toEqual([
+      ['awaiting', 3],
+      ['zeta', 2],
+      ['alpha', 4],
+    ])
+    expect(view.filters.map((filter) => [filter.subjectType, filter.unreadCount])).toEqual([
+      ['all', 9],
+      ['zeta', 5],
+      ['alpha', 4],
+    ])
+  })
+
+  it('places every conversation in exactly one section', () => {
+    const conversations = [
+      build({ subjectId: '1', subjectType: 'zeta', status: 'closed' }),
+      build({ subjectId: '2', subjectType: 'alpha', awaitingParticipant: true }),
+      build({ subjectId: '3', subjectType: 'nope' }),
+      build({ subjectId: '4', subjectType: 'alpha' }),
+      build({ subjectId: '5', subjectType: 'zeta', lastMessageAt: null }),
+    ]
+    const view = groupParticipantConversations({ subjectGroups: GROUPS, conversations })
+    const total = view.sections.reduce((sum, section) => sum + section.conversations.length, 0)
+    expect(total).toBe(conversations.length)
+  })
+
+  it('sends unknown subjectType to other and never drops it', () => {
+    const view = groupParticipantConversations({
+      subjectGroups: GROUPS,
+      conversations: [build({ subjectId: '1', subjectType: 'mystery' })],
+    })
+    expect(keysOf(view)).toEqual(['other'])
+  })
+
+  it('shows filters only with two or more groups that have conversations', () => {
+    const one = groupParticipantConversations({
+      subjectGroups: GROUPS,
+      conversations: [build({ subjectId: '1', subjectType: 'zeta' })],
+    })
+    expect(one.showFilters).toBe(false)
+    const two = groupParticipantConversations({
+      subjectGroups: GROUPS,
+      conversations: [build({ subjectId: '1', subjectType: 'zeta' }), build({ subjectId: '2', subjectType: 'alpha' })],
+    })
+    expect(two.showFilters).toBe(true)
+  })
+
+  it('restricts every section to the filtered subjectType, including awaiting', () => {
+    const view = groupParticipantConversations({
+      subjectGroups: GROUPS,
+      filter: 'alpha',
+      conversations: [
+        build({ subjectId: '1', subjectType: 'zeta', awaitingParticipant: true }),
+        build({ subjectId: '2', subjectType: 'alpha', awaitingParticipant: true }),
+        build({ subjectId: '3', subjectType: 'alpha' }),
+        build({ subjectId: '4', subjectType: 'zeta' }),
+      ],
+    })
+    expect(view.sections.map((section) => section.conversations.map((c) => c.subjectId))).toEqual([['2'], ['3']])
+    expect(groupParticipantConversations({ subjectGroups: GROUPS, filter: 'all', conversations: [build({ subjectId: '1' })] }).sections).toHaveLength(1)
+  })
+})

package/src/participant/participantGrouping.ts

@@ -0,0 +1,77 @@
+import type { ParticipantConversationSummary } from '@adatechnology/conversation-contracts'
+
+import type {
+  GroupParticipantConversationsParams,
+  ParticipantInboxFilter,
+  ParticipantInboxSection,
+  ParticipantInboxView,
+} from './participant.types'
+
+const ALL_FILTER = 'all'
+const SECTION_AWAITING = 'awaiting'
+const SECTION_OTHER = 'other'
+const SECTION_CLOSED = 'closed'
+
+function compareConversations(left: ParticipantConversationSummary, right: ParticipantConversationSummary): number {
+  if (left.lastMessageAt !== right.lastMessageAt) {
+    if (left.lastMessageAt === null) return 1
+    if (right.lastMessageAt === null) return -1
+    return left.lastMessageAt < right.lastMessageAt ? 1 : -1
+  }
+  return left.subjectLabel.localeCompare(right.subjectLabel)
+}
+
+function sumUnread(conversations: readonly ParticipantConversationSummary[]): number {
+  return conversations.reduce((sum, conversation) => sum + conversation.unreadCount, 0)
+}
+
+function resolveSectionKey(conversation: ParticipantConversationSummary, knownTypes: ReadonlySet<string>): string {
+  if (conversation.status === 'closed') return SECTION_CLOSED
+  if (conversation.awaitingParticipant) return SECTION_AWAITING
+  return knownTypes.has(conversation.subjectType) ? conversation.subjectType : SECTION_OTHER
+}
+
+function buildSection(key: string, conversations: readonly ParticipantConversationSummary[]): ParticipantInboxSection {
+  const sorted = [...conversations].sort(compareConversations)
+  return { key, conversations: sorted, unreadCount: sumUnread(sorted) }
+}
+
+function buildFilters(
+  params: GroupParticipantConversationsParams,
+): Pick<ParticipantInboxView, 'filters' | 'showFilters'> {
+  const groupFilters: ParticipantInboxFilter[] = []
+  for (const group of params.subjectGroups) {
+    const own = params.conversations.filter((conversation) => conversation.subjectType === group.subjectType)
+    if (own.length === 0) continue
+    groupFilters.push({ subjectType: group.subjectType, label: group.label, unreadCount: sumUnread(own) })
+  }
+  const all: ParticipantInboxFilter = {
+    subjectType: ALL_FILTER,
+    label: 'All',
+    unreadCount: sumUnread(params.conversations),
+  }
+  return { filters: [all, ...groupFilters], showFilters: groupFilters.length >= 2 }
+}
+
+export function groupParticipantConversations(params: GroupParticipantConversationsParams): ParticipantInboxView {
+  const { filter, subjectGroups } = params
+  const isFiltered = filter !== undefined && filter !== ALL_FILTER
+  const visible = isFiltered
+    ? params.conversations.filter((conversation) => conversation.subjectType === filter)
+    : params.conversations
+  const knownTypes = new Set(subjectGroups.map((group) => group.subjectType))
+
+  const buckets = new Map<string, ParticipantConversationSummary[]>()
+  for (const conversation of visible) {
+    const key = resolveSectionKey(conversation, knownTypes)
+    buckets.set(key, [...(buckets.get(key) ?? []), conversation])
+  }
+
+  const orderedKeys = [SECTION_AWAITING, ...subjectGroups.map((group) => group.subjectType), SECTION_OTHER, SECTION_CLOSED]
+  const sections = orderedKeys.flatMap((key) => {
+    const bucket = buckets.get(key)
+    return bucket === undefined ? [] : [buildSection(key, bucket)]
+  })
+
+  return { sections, ...buildFilters(params) }
+}

package/src/participant/participantInboxState.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'bun:test'
+
+import type { ParticipantConversationSummary } from '@adatechnology/conversation-contracts'
+
+import { INITIAL_PARTICIPANT_INBOX_STATE, participantInboxReducer } from './participantInboxState'
+
+function conversation(subjectId: string, unreadCount = 0, subjectType = 'trip'): ParticipantConversationSummary {
+  return { subjectType, subjectId, subjectLabel: subjectId, lastMessageAt: null, unreadCount, awaitingParticipant: false, status: 'open' }
+}
+
+describe('participantInboxReducer', () => {
+  it('starts idle and goes to loading on started', () => {
+    expect(INITIAL_PARTICIPANT_INBOX_STATE.status).toBe('idle')
+    expect(participantInboxReducer(INITIAL_PARTICIPANT_INBOX_STATE, { type: 'started' }).status).toBe('loading')
+  })
+
+  it('keeps ready status while revalidating', () => {
+    const ready = participantInboxReducer(INITIAL_PARTICIPANT_INBOX_STATE, { type: 'loaded', conversations: [conversation('a')] })
+    expect(participantInboxReducer(ready, { type: 'started' }).status).toBe('ready')
+  })
+
+  it('loaded stores the list and the cursor', () => {
+    const state = participantInboxReducer(INITIAL_PARTICIPANT_INBOX_STATE, { type: 'loaded', conversations: [conversation('a')], nextCursor: 'c1' })
+    expect(state).toMatchObject({ status: 'ready', nextCursor: 'c1' })
+    const replaced = participantInboxReducer(state, { type: 'loaded', conversations: [conversation('a')] })
+    expect(replaced.conversations.map((item) => item.subjectId)).toEqual(['a'])
+    expect(replaced.nextCursor).toBeUndefined()
+  })
+
+  it('loaded (revalidation) keeps the appended pages and lets the newest version of a subject win', () => {
+    const first = participantInboxReducer(INITIAL_PARTICIPANT_INBOX_STATE, { type: 'loaded', conversations: [conversation('a'), conversation('b')], nextCursor: 'c1' })
+    const paged = participantInboxReducer(first, { type: 'appended', conversations: [conversation('c'), conversation('d')], nextCursor: 'c2' })
+    const revalidated = participantInboxReducer(paged, { type: 'loaded', conversations: [conversation('b', 7), conversation('a')], nextCursor: 'c1' })
+
+    expect(revalidated.conversations.map((item) => item.subjectId)).toEqual(['b', 'a', 'c', 'd'])
+    expect(revalidated.conversations[0]?.unreadCount).toBe(7)
+    expect(revalidated.nextCursor).toBe('c2')
+  })
+
+  it('loaded takes the new cursor when no extra pages were appended', () => {
+    const first = participantInboxReducer(INITIAL_PARTICIPANT_INBOX_STATE, { type: 'loaded', conversations: [conversation('a')], nextCursor: 'c1' })
+    const revalidated = participantInboxReducer(first, { type: 'loaded', conversations: [conversation('a')], nextCursor: 'c9' })
+    expect(revalidated.nextCursor).toBe('c9')
+  })
+
+  it('appended adds the next page without duplicating a subject', () => {
+    const first = participantInboxReducer(INITIAL_PARTICIPANT_INBOX_STATE, { type: 'loaded', conversations: [conversation('a'), conversation('b')], nextCursor: 'c1' })
+    const next = participantInboxReducer(first, { type: 'appended', conversations: [conversation('b', 3), conversation('c')] })
+    expect(next.conversations.map((item) => item.subjectId)).toEqual(['a', 'b', 'c'])
+    expect(next.conversations[1]?.unreadCount).toBe(3)
+    expect(next.nextCursor).toBeUndefined()
+  })
+
+  it('markedRead zeroes only that subject', () => {
+    const loaded = participantInboxReducer(INITIAL_PARTICIPANT_INBOX_STATE, {
+      type: 'loaded',
+      conversations: [conversation('a', 2), conversation('b', 4), conversation('a', 5, 'invoice')],
+    })
+    const next = participantInboxReducer(loaded, { type: 'markedRead', subject: { subjectType: 'trip', subjectId: 'a' } })
+    expect(next.conversations.map((item) => item.unreadCount)).toEqual([0, 4, 5])
+  })
+
+  it('failed records the error and keeps the conversations', () => {
+    const loaded = participantInboxReducer(INITIAL_PARTICIPANT_INBOX_STATE, { type: 'loaded', conversations: [conversation('a')] })
+    const failed = participantInboxReducer(loaded, { type: 'failed', error: 'boom' })
+    expect(failed).toMatchObject({ status: 'error', error: 'boom' })
+    expect(failed.conversations).toHaveLength(1)
+  })
+})

package/src/participant/participantInboxState.ts

@@ -0,0 +1,74 @@
+import type { ParticipantConversationSummary, ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+export type ParticipantInboxState = {
+  readonly status: 'idle' | 'loading' | 'ready' | 'error'
+  readonly conversations: readonly ParticipantConversationSummary[]
+  readonly nextCursor?: string
+  readonly error?: string
+}
+
+export type ParticipantInboxAction =
+  | { readonly type: 'started' }
+  | { readonly type: 'loaded'; readonly conversations: readonly ParticipantConversationSummary[]; readonly nextCursor?: string }
+  | { readonly type: 'appended'; readonly conversations: readonly ParticipantConversationSummary[]; readonly nextCursor?: string }
+  | { readonly type: 'markedRead'; readonly subject: ParticipantSubjectRef }
+  | { readonly type: 'failed'; readonly error: string }
+
+export const INITIAL_PARTICIPANT_INBOX_STATE: ParticipantInboxState = { status: 'idle', conversations: [] }
+
+function subjectKey(subject: ParticipantSubjectRef): string {
+  return `${subject.subjectType}:${subject.subjectId}`
+}
+
+function withCursor(
+  state: ParticipantInboxState,
+  conversations: readonly ParticipantConversationSummary[],
+  nextCursor: string | undefined,
+): ParticipantInboxState {
+  const { error: _error, nextCursor: _nextCursor, ...rest } = state
+  return { ...rest, status: 'ready', conversations, ...(nextCursor === undefined ? {} : { nextCursor }) }
+}
+
+/** Revalidation brings the first page again: it must not drop the pages appended after it. */
+function mergeFirstPage(
+  state: ParticipantInboxState,
+  incoming: readonly ParticipantConversationSummary[],
+  nextCursor: string | undefined,
+): ParticipantInboxState {
+  const incomingKeys = new Set(incoming.map(subjectKey))
+  const retained = state.conversations.filter((conversation) => !incomingKeys.has(subjectKey(conversation)))
+  const cursor = retained.length > 0 ? state.nextCursor : nextCursor
+  return withCursor(state, [...incoming, ...retained], cursor)
+}
+
+function appendUnique(
+  current: readonly ParticipantConversationSummary[],
+  incoming: readonly ParticipantConversationSummary[],
+): readonly ParticipantConversationSummary[] {
+  const incomingByKey = new Map(incoming.map((conversation) => [subjectKey(conversation), conversation]))
+  const updated = current.map((conversation) => incomingByKey.get(subjectKey(conversation)) ?? conversation)
+  const knownKeys = new Set(current.map(subjectKey))
+  return [...updated, ...incoming.filter((conversation) => !knownKeys.has(subjectKey(conversation)))]
+}
+
+export function participantInboxReducer(state: ParticipantInboxState, action: ParticipantInboxAction): ParticipantInboxState {
+  switch (action.type) {
+    case 'started':
+      return state.status === 'ready' ? state : { ...state, status: 'loading' }
+    case 'loaded':
+      return mergeFirstPage(state, action.conversations, action.nextCursor)
+    case 'appended':
+      return withCursor(state, appendUnique(state.conversations, action.conversations), action.nextCursor)
+    case 'markedRead': {
+      const target = subjectKey(action.subject)
+      return {
+        ...state,
+        conversations: state.conversations.map((conversation) =>
+          subjectKey(conversation) === target ? { ...conversation, unreadCount: 0 } : conversation,
+        ),
+      }
+    }
+    case 'failed':
+      return { ...state, status: 'error', error: action.error }
+  }
+}

package/src/participant/participantLabels.ts

@@ -0,0 +1,86 @@
+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
+}
+
+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',
+}
+
+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,
+  }
+}