@adatechnology/conversations-ui 0.4.2 → 0.6.0

package/src/participant/ParticipantThreadScreen.tsx

@@ -0,0 +1,135 @@
+import { useEffect, useMemo, useState, type Dispatch, type MutableRefObject } from 'react'
+
+import type { ParticipantConversationSummary, ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+import { ParticipantThread } from './ParticipantThread'
+import type { ParticipantConversationsScreenProps } from './ParticipantConversationsScreen'
+import { bindAttachmentUrlResolver } from './bindAttachmentUrlResolver'
+import type { ParticipantDrafts } from './participantDrafts'
+import type { ParticipantConversationsLabels } from './participantLabels'
+import type { ParticipantConversationsApi } from './participantApi.types'
+import { findFailedEntry, hasSendingEntry } from './participantSendController'
+import type { ParticipantSendStates, ParticipantSendStatesAction } from './participantSendStates'
+import { useParticipantDraft } from './useParticipantDraft'
+import { useParticipantConversationView } from './useParticipantConversationView'
+import { useParticipantThreadScroll } from './useParticipantThreadScroll'
+
+export type ParticipantThreadScreenProps = Omit<ParticipantConversationsScreenProps, 'selected' | 'labels'> & {
+  readonly selected: ParticipantSubjectRef
+  readonly labels: ParticipantConversationsLabels
+  /** Holds the immutable drafts of every subject; replaced, never mutated. */
+  readonly draftsRef: MutableRefObject<ParticipantDrafts>
+  /** Sends of every subject; they live above the conversation so a failed message survives leaving it. */
+  readonly sendStates: ParticipantSendStates
+  readonly dispatchSendStates: Dispatch<ParticipantSendStatesAction>
+}
+
+type OpenedState = { readonly status: 'idle' | 'loading' | 'missing' } | { readonly status: 'found'; readonly conversation: ParticipantConversationSummary }
+
+function useOpenedConversation(api: ParticipantConversationsApi, subject: ParticipantSubjectRef, isNeeded: boolean): OpenedState {
+  const [opened, setOpened] = useState<OpenedState>({ status: 'idle' })
+  const { subjectType, subjectId } = subject
+  const canOpen = api.openConversation !== undefined
+
+  useEffect(() => {
+    if (!isNeeded || !canOpen) return
+    let isCurrent = true
+    setOpened({ status: 'loading' })
+    api.openConversation?.({ subjectType, subjectId }).then(
+      (conversation) => isCurrent && setOpened({ status: 'found', conversation }),
+      () => isCurrent && setOpened({ status: 'missing' }),
+    )
+    return () => {
+      isCurrent = false
+    }
+  }, [api, canOpen, isNeeded, subjectType, subjectId])
+
+  return opened
+}
+
+function NotFound({ labels, onBack }: { readonly labels: ParticipantConversationsLabels; readonly onBack?: () => void }) {
+  return (
+    <div className="cv-p cv-p-thread">
+      <header className="cv-p-thread__header">
+        {onBack ? (
+          <button type="button" className="cv-p-button cv-p-thread__back" onClick={onBack}>
+            <span aria-hidden="true">‹</span>
+            <span className="cv-p-sr-only">{labels.back}</span>
+          </button>
+        ) : null}
+      </header>
+      <p className="cv-p-empty">{labels.notFound}</p>
+    </div>
+  )
+}
+
+export function ParticipantThreadScreen(props: ParticipantThreadScreenProps) {
+  const { api, selected, inbox, labels } = props
+  const listed = inbox.conversations.find(
+    (item) => item.subjectType === selected.subjectType && item.subjectId === selected.subjectId,
+  )
+  const opened = useOpenedConversation(api, selected, listed === undefined)
+  const conversation = listed ?? (opened.status === 'found' ? opened.conversation : undefined)
+
+  if (conversation) return <LoadedThread {...props} conversation={conversation} />
+  const isResolving = opened.status === 'loading' || (api.openConversation !== undefined && opened.status === 'idle')
+  const isListLoading = inbox.status === 'idle' || inbox.status === 'loading'
+  if (isResolving || (api.openConversation === undefined && isListLoading)) return <div className="cv-p cv-p-thread" aria-busy="true" />
+  return <NotFound labels={labels} onBack={props.onBack} />
+}
+
+type LoadedThreadProps = ParticipantThreadScreenProps & { readonly conversation: ParticipantConversationSummary }
+
+function LoadedThread(props: LoadedThreadProps) {
+  const { api, selected, conversation, draftsRef, inbox } = props
+  const { draft, setText, setFiles, takeForSend, restoreFromEntry } = useParticipantDraft(draftsRef, selected)
+  const { thread, items, sendEntries, dispatchSend } = useParticipantConversationView({
+    ...props,
+    subject: selected,
+    onMarkedRead: inbox.markSubjectRead,
+  })
+  const resolveAttachmentUrl = useMemo(() => bindAttachmentUrlResolver(api), [api])
+  const { scroll, newMessagesCount } = useParticipantThreadScroll(items)
+
+  function handleSend(): void {
+    const content = takeForSend()
+    if (content) void thread.send(content)
+  }
+
+  function handleEdit(clientMessageId: string): void {
+    const entry = findFailedEntry(sendEntries, clientMessageId)
+    if (!entry) return
+    restoreFromEntry(entry)
+    dispatchSend({ type: 'discarded', clientMessageId })
+  }
+
+  return (
+    <ParticipantThread
+      conversation={conversation}
+      items={items}
+      hasMore={thread.hasMore}
+      labels={props.labels}
+      resolveAttachmentUrl={resolveAttachmentUrl}
+      draft={{ value: draft.text, onChange: setText, files: draft.files, onFilesChange: setFiles }}
+      onSend={handleSend}
+      status={thread.status}
+      refresh={() => void thread.refresh()}
+      scroll={scroll}
+      newMessagesCount={newMessagesCount}
+      isSending={hasSendingEntry(sendEntries)}
+      channel={props.channel}
+      locale={props.locale}
+      onBack={props.onBack}
+      onOpenSubject={props.onOpenSubject}
+      onLoadOlder={() => void thread.loadOlder()}
+      pendingActions={{
+        retryLocal: (clientMessageId) => void thread.retry(clientMessageId),
+        discardLocal: (clientMessageId) => dispatchSend({ type: 'discarded', clientMessageId }),
+        editLocal: handleEdit,
+        ...(props.onRetryPending ? { retryHost: props.onRetryPending } : {}),
+      }}
+      quickReplies={props.quickReplies}
+      renderSubjectCard={props.renderSubjectCard}
+    />
+  )
+}

package/src/participant/bindAttachmentUrlResolver.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'bun:test'
+
+import type { ParticipantAttachment } from '@adatechnology/conversation-contracts'
+
+import type { ParticipantConversationsApi } from './participantApi.types'
+import { bindAttachmentUrlResolver } from './bindAttachmentUrlResolver'
+
+class ClassAdapter {
+  readonly baseUrl = 'https://files.example'
+
+  async resolveAttachmentUrl(attachment: ParticipantAttachment, disposition: 'inline' | 'attachment' = 'inline'): Promise<string> {
+    return `${this.baseUrl}/${attachment.id}?disposition=${disposition}`
+  }
+}
+
+describe('bindAttachmentUrlResolver', () => {
+  it('keeps the adapter as this, which a detached method reference would lose', async () => {
+    const adapter = new ClassAdapter()
+    const attachment: ParticipantAttachment = { id: 'a1', kind: 'image', filename: 'a.png', mimeType: 'image/png', sizeBytes: 1 }
+    const resolve = bindAttachmentUrlResolver(adapter as unknown as ParticipantConversationsApi)
+
+    expect(await resolve(attachment, 'attachment')).toBe('https://files.example/a1?disposition=attachment')
+    expect(await resolve(attachment)).toBe('https://files.example/a1?disposition=inline')
+  })
+})

package/src/participant/bindAttachmentUrlResolver.ts

@@ -0,0 +1,7 @@
+import type { ResolveParticipantAttachmentUrl } from './ParticipantAttachmentItem'
+import type { ParticipantConversationsApi } from './participantApi.types'
+
+/** A detached method reference loses `this`; adapters written as classes break without the wrapper. */
+export function bindAttachmentUrlResolver(api: ParticipantConversationsApi): ResolveParticipantAttachmentUrl {
+  return (attachment, disposition) => api.resolveAttachmentUrl(attachment, disposition)
+}

package/src/participant/index.ts

@@ -0,0 +1,26 @@
+export { ParticipantConversations, type ParticipantConversationsProps } from './ParticipantConversations'
+export { groupParticipantConversations } from './participantGrouping'
+export { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS, type ParticipantConversationsLabels } from './participantLabels'
+export type {
+  ParticipantConversationsClassNames,
+  ParticipantSubjectGroup,
+  ParticipantSubjectIconRenderer,
+  ParticipantInboxView,
+  ParticipantInboxSection,
+  GroupParticipantConversationsParams,
+} from './participant.types'
+export type {
+  ParticipantConversationEvent,
+  ParticipantConversationsApi,
+  ParticipantLocalPendingMessage,
+  ParticipantPendingMessage,
+  ParticipantSendInput,
+  ParticipantSendResult,
+} from './participantApi.types'
+export type {
+  ParticipantAttachment,
+  ParticipantConversationPage,
+  ParticipantConversationSummary,
+  ParticipantMessage,
+  ParticipantSubjectRef,
+} from '@adatechnology/conversation-contracts'

package/src/participant/participant.types.ts

@@ -0,0 +1,52 @@
+import type { ReactNode } from 'react'
+
+import type { ParticipantConversationSummary } from '@adatechnology/conversation-contracts'
+
+export type ParticipantSubjectGroup = {
+  readonly subjectType: string
+  readonly label: string
+  readonly icon?: ReactNode
+}
+
+/** Host-drawn icon for a list row; null/undefined falls back to the subject group icon. */
+export type ParticipantSubjectIconRenderer = (conversation: ParticipantConversationSummary) => ReactNode
+
+export type ParticipantInboxSection = {
+  /** 'awaiting' | 'closed' | 'other' or the subjectType of a group. */
+  readonly key: string
+  /** Absent for groups: the host resolves it from subjectGroups. */
+  readonly label?: string
+  readonly conversations: readonly ParticipantConversationSummary[]
+  readonly unreadCount: number
+}
+
+export type ParticipantInboxFilter = {
+  readonly subjectType: string
+  readonly label: string
+  readonly unreadCount: number
+}
+
+export type ParticipantInboxView = {
+  readonly sections: readonly ParticipantInboxSection[]
+  readonly filters: readonly ParticipantInboxFilter[]
+  readonly showFilters: boolean
+  /** The filter actually applied: 'all' when the requested one has no conversations left. */
+  readonly activeFilter: string
+  /** The search finds conversations, but none under the active subject filter. */
+  readonly hasMatchesOutsideFilter: boolean
+}
+
+export type GroupParticipantConversationsParams = {
+  readonly conversations: readonly ParticipantConversationSummary[]
+  readonly subjectGroups: readonly ParticipantSubjectGroup[]
+  /** subjectType, or 'all'/undefined for everything. */
+  readonly filter?: string
+  /** Narrows the rows only: chips and their counts always describe the whole list. */
+  readonly searchQuery?: string
+}
+
+export type ParticipantConversationsClassNames = {
+  readonly root: string
+  readonly inbox: string
+  readonly thread: string
+}

package/src/participant/participantApi.types.ts

@@ -0,0 +1,59 @@
+import type {
+  ParticipantAttachment,
+  ParticipantConversationPage,
+  ParticipantConversationSummary,
+  ParticipantMessage,
+  ParticipantSubjectRef,
+} from '@adatechnology/conversation-contracts'
+
+export type ParticipantSendInput = {
+  readonly subject: ParticipantSubjectRef
+  /** Generated by the package (crypto.randomUUID). The host uses it as Idempotency-Key; a resend repeats it. */
+  readonly clientMessageId: string
+  readonly text?: string
+  readonly files?: readonly File[]
+}
+
+export type ParticipantSendResult =
+  | { readonly outcome: 'sent'; readonly message: ParticipantMessage }
+  | { readonly outcome: 'queued' }
+
+export type ParticipantConversationEvent =
+  | { readonly type: 'inbox-changed' }
+  | { readonly type: 'conversation-changed'; readonly subject: ParticipantSubjectRef }
+
+export interface ParticipantConversationsApi {
+  listConversations(params?: { readonly cursor?: string }): Promise<ParticipantConversationPage>
+  fetchMessages(
+    subject: ParticipantSubjectRef,
+    params?: { readonly before?: string; readonly limit?: number },
+  ): Promise<readonly ParticipantMessage[]>
+  /** Throwing means failed; the package shows a retry affordance and repeats the SAME clientMessageId. */
+  sendMessage(input: ParticipantSendInput): Promise<ParticipantSendResult>
+  /** Marks the other side's messages of THAT subject as read, never "all". */
+  markRead(subject: ParticipantSubjectRef): Promise<void>
+  resolveAttachmentUrl(attachment: ParticipantAttachment, disposition?: 'inline' | 'attachment'): Promise<string>
+  openConversation?(subject: ParticipantSubjectRef): Promise<ParticipantConversationSummary>
+  subscribe?(listener: (event: ParticipantConversationEvent) => void): () => void
+}
+
+type ParticipantPendingAttachment = {
+  readonly filename: string
+  readonly mimeType: string
+  readonly sizeBytes: number
+}
+
+/** Message the host keeps in its durable queue and hands back to the package. */
+export type ParticipantPendingMessage = {
+  readonly clientMessageId: string
+  readonly subject: ParticipantSubjectRef
+  readonly text?: string
+  readonly attachments?: readonly ParticipantPendingAttachment[]
+  readonly createdAt: string
+  readonly state: 'queued' | 'failed'
+}
+
+/** Message still living only in the memory of the screen: being sent, queued by the host and not yet reflected, sent but not yet echoed, or failed. */
+export type ParticipantLocalPendingMessage = Omit<ParticipantPendingMessage, 'state'> & {
+  readonly state: 'sending' | 'queued' | 'failed' | 'sent'
+}

package/src/participant/participantAttachmentUrl.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'bun:test'
+
+import { isSafeAttachmentUrl } from './participantAttachmentUrl'
+
+describe('isSafeAttachmentUrl', () => {
+  it('accepts https, http and blob', () => {
+    expect(isSafeAttachmentUrl('https://cdn.example.com/a.png?sig=1')).toBe(true)
+    expect(isSafeAttachmentUrl('http://localhost:3000/a.png')).toBe(true)
+    expect(isSafeAttachmentUrl('blob:https://app.example.com/0b1c')).toBe(true)
+  })
+
+  it('rejects script and data schemes in any casing or with surrounding whitespace', () => {
+    expect(isSafeAttachmentUrl('javascript:alert(1)')).toBe(false)
+    expect(isSafeAttachmentUrl('JaVaScRiPt:alert(1)')).toBe(false)
+    expect(isSafeAttachmentUrl('  javascript:alert(1)')).toBe(false)
+    expect(isSafeAttachmentUrl('java\tscript:alert(1)')).toBe(false)
+    expect(isSafeAttachmentUrl('data:text/html,<script>alert(1)</script>')).toBe(false)
+    expect(isSafeAttachmentUrl('vbscript:msgbox(1)')).toBe(false)
+  })
+
+  it('accepts a safe scheme in mixed case and with surrounding whitespace', () => {
+    expect(isSafeAttachmentUrl(' HTTPS://cdn.example.com/a.png ')).toBe(true)
+  })
+
+  it('rejects empty and relative urls', () => {
+    expect(isSafeAttachmentUrl('')).toBe(false)
+    expect(isSafeAttachmentUrl('   ')).toBe(false)
+    expect(isSafeAttachmentUrl('/files/a.png')).toBe(false)
+    expect(isSafeAttachmentUrl('a.png')).toBe(false)
+    expect(isSafeAttachmentUrl('//evil.example.com/a.png')).toBe(false)
+  })
+})

package/src/participant/participantAttachmentUrl.ts

@@ -0,0 +1,10 @@
+const SAFE_ATTACHMENT_PROTOCOLS: ReadonlySet<string> = new Set(['https:', 'http:', 'blob:'])
+
+/** The resolved URL comes from the host: only network and blob schemes reach href/src; relative urls are refused. */
+export function isSafeAttachmentUrl(url: string): boolean {
+  try {
+    return SAFE_ATTACHMENT_PROTOCOLS.has(new URL(url.trim()).protocol)
+  } catch {
+    return false
+  }
+}

package/src/participant/participantBubbleActions.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'bun:test'
+
+import type { ParticipantTimelineItem } from './participantMessages'
+import { resolveParticipantBubbleActions } from './participantBubbleActions'
+
+const SUBJECT = { subjectType: 'trip', subjectId: 'a' }
+const noop = (): void => undefined
+
+function pendingItem(origin: 'host' | 'local', displayState: 'sending' | 'queued' | 'failed'): ParticipantTimelineItem {
+  return {
+    kind: 'pending',
+    origin,
+    displayState,
+    pending: { clientMessageId: 'c1', subject: SUBJECT, createdAt: '2026-10-01T10:00:00.000Z', state: displayState === 'sending' ? 'failed' : displayState },
+  }
+}
+
+const HANDLERS = { retryLocal: noop, discardLocal: noop, editLocal: noop }
+
+describe('resolveParticipantBubbleActions', () => {
+  it('a failed local pending offers retry, discard and edit', () => {
+    const actions = resolveParticipantBubbleActions(pendingItem('local', 'failed'), HANDLERS)
+    expect(Object.keys(actions).sort()).toEqual(['onDiscard', 'onEdit', 'onRetry'])
+  })
+
+  it('a pending that is not failed offers nothing', () => {
+    expect(resolveParticipantBubbleActions(pendingItem('local', 'sending'), HANDLERS)).toEqual({})
+    expect(resolveParticipantBubbleActions(pendingItem('local', 'queued'), HANDLERS)).toEqual({})
+  })
+
+  it('a failed host pending offers retry only when the host gave onRetryPending, never discard or edit', () => {
+    expect(resolveParticipantBubbleActions(pendingItem('host', 'failed'), HANDLERS)).toEqual({})
+    const withHost = resolveParticipantBubbleActions(pendingItem('host', 'failed'), { ...HANDLERS, retryHost: noop })
+    expect(Object.keys(withHost)).toEqual(['onRetry'])
+  })
+
+  it('a failed server message never offers any action', () => {
+    const item: ParticipantTimelineItem = {
+      kind: 'server',
+      message: { id: 'm1', direction: 'inbound', attachments: [], createdAt: '2026-10-01T10:00:00.000Z', status: 'failed', clientMessageId: 'c1' },
+    }
+    expect(resolveParticipantBubbleActions(item, { ...HANDLERS, retryHost: noop })).toEqual({})
+  })
+})

package/src/participant/participantBubbleActions.ts

@@ -0,0 +1,40 @@
+import type { ParticipantTimelineItem } from './participantMessages'
+
+export type ParticipantBubbleActions = {
+  readonly onRetry?: () => void
+  readonly onDiscard?: () => void
+  readonly onEdit?: () => void
+}
+
+export type ParticipantBubbleHandlers = {
+  readonly retryLocal: () => void
+  readonly discardLocal: () => void
+  readonly editLocal: () => void
+  /** Absent when the host did not pass onRetryPending: there is no way to resend what is in its queue. */
+  readonly retryHost?: () => void
+}
+
+/** Same handlers, addressed by clientMessageId; the thread binds them to each bubble. */
+export type ParticipantPendingActions = {
+  readonly retryLocal: (clientMessageId: string) => void
+  readonly discardLocal: (clientMessageId: string) => void
+  readonly editLocal: (clientMessageId: string) => void
+  readonly retryHost?: (clientMessageId: string) => void
+}
+
+export function bindPendingActions(actions: ParticipantPendingActions, clientMessageId: string): ParticipantBubbleHandlers {
+  const { retryHost } = actions
+  return {
+    retryLocal: () => actions.retryLocal(clientMessageId),
+    discardLocal: () => actions.discardLocal(clientMessageId),
+    editLocal: () => actions.editLocal(clientMessageId),
+    ...(retryHost ? { retryHost: () => retryHost(clientMessageId) } : {}),
+  }
+}
+
+/** Only a failed pending can act; a failed server message has no way to be resent, so it just says "Failed". */
+export function resolveParticipantBubbleActions(item: ParticipantTimelineItem, handlers: ParticipantBubbleHandlers): ParticipantBubbleActions {
+  if (item.kind === 'server' || item.displayState !== 'failed') return {}
+  if (item.origin === 'host') return handlers.retryHost ? { onRetry: handlers.retryHost } : {}
+  return { onRetry: handlers.retryLocal, onDiscard: handlers.discardLocal, onEdit: handlers.editLocal }
+}

package/src/participant/participantChannels.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'bun:test'
+
+import { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS } from './participantLabels'
+import {
+  PARTICIPANT_CHANNEL_ORDER,
+  resolveParticipantChannelLabel,
+  resolveParticipantChannels,
+} from './participantChannels'
+
+const channelsOf = (input: readonly string[] | undefined) =>
+  resolveParticipantChannels(input).map((descriptor) => descriptor.channel)
+
+describe('resolveParticipantChannels', () => {
+  it('returns nothing for absent or empty input', () => {
+    expect(channelsOf(undefined)).toEqual([])
+    expect(channelsOf([])).toEqual([])
+  })
+
+  it('orders deterministically whatever the server order', () => {
+    expect(channelsOf(['webchat', 'email', 'whatsapp', 'app', 'portal'])).toEqual([
+      'app',
+      'whatsapp',
+      'email',
+      'portal',
+      'webchat',
+    ])
+    expect(channelsOf(['whatsapp', 'app'])).toEqual(['app', 'whatsapp'])
+  })
+
+  it('dedupes and ignores unknown channels', () => {
+    expect(channelsOf(['whatsapp', 'whatsapp', 'sms', 'app'])).toEqual(['app', 'whatsapp'])
+  })
+
+  it('maps every channel to an icon and a label', () => {
+    expect(PARTICIPANT_CHANNEL_ORDER).toHaveLength(5)
+    const labels = PARTICIPANT_CHANNEL_ORDER.map((descriptor) =>
+      resolveParticipantChannelLabel(descriptor, DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS),
+    )
+    expect(labels).toEqual(['App', 'WhatsApp', 'Email', 'Portal', 'Web chat'])
+    expect(new Set(PARTICIPANT_CHANNEL_ORDER.map((descriptor) => descriptor.iconName)).size).toBe(5)
+  })
+})

package/src/participant/participantChannels.ts

@@ -0,0 +1,33 @@
+import type { ConversationChannel } from '@adatechnology/conversation-contracts'
+
+import type { ParticipantConversationsLabels } from './participantLabels'
+
+export type ParticipantChannelDescriptor = {
+  readonly channel: ConversationChannel
+  readonly iconName: 'Smartphone' | 'MessageCircle' | 'Mail' | 'Globe' | 'MessagesSquare'
+  readonly labelKey: 'channelApp' | 'channelWhatsapp' | 'channelEmail' | 'channelPortal' | 'channelWebchat'
+}
+
+export const PARTICIPANT_CHANNEL_ORDER: readonly ParticipantChannelDescriptor[] = [
+  { channel: 'app', iconName: 'Smartphone', labelKey: 'channelApp' },
+  { channel: 'whatsapp', iconName: 'MessageCircle', labelKey: 'channelWhatsapp' },
+  { channel: 'email', iconName: 'Mail', labelKey: 'channelEmail' },
+  { channel: 'portal', iconName: 'Globe', labelKey: 'channelPortal' },
+  { channel: 'webchat', iconName: 'MessagesSquare', labelKey: 'channelWebchat' },
+]
+
+/** Stable badge order regardless of the server order; duplicates and unknown values (runtime) are dropped. */
+export function resolveParticipantChannels(
+  channels: readonly string[] | undefined,
+): readonly ParticipantChannelDescriptor[] {
+  if (channels === undefined || channels.length === 0) return []
+  const present = new Set<string>(channels)
+  return PARTICIPANT_CHANNEL_ORDER.filter((descriptor) => present.has(descriptor.channel))
+}
+
+export function resolveParticipantChannelLabel(
+  descriptor: ParticipantChannelDescriptor,
+  labels: ParticipantConversationsLabels,
+): string {
+  return labels[descriptor.labelKey]
+}

package/src/participant/participantDrafts.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'bun:test'
+
+import { clearDraft, takeDraftForSend, draftKey, EMPTY_PARTICIPANT_DRAFT, getDraft, setDraft } from './participantDrafts'
+
+const TRIP_A = { subjectType: 'trip', subjectId: 'a' }
+const TRIP_B = { subjectType: 'trip', subjectId: 'b' }
+const INVOICE_A = { subjectType: 'invoice', subjectId: 'a' }
+
+describe('participantDrafts', () => {
+  it('builds the key from subject type and id', () => {
+    expect(draftKey(TRIP_A)).toBe('trip:a')
+    expect(draftKey(INVOICE_A)).not.toBe(draftKey(TRIP_A))
+  })
+
+  it('returns an empty draft for an unknown subject', () => {
+    expect(getDraft(new Map(), TRIP_A)).toEqual({ text: '', files: [] })
+    expect(getDraft(new Map(), TRIP_A)).toBe(EMPTY_PARTICIPANT_DRAFT)
+  })
+
+  it('does not leak a draft to another subject', () => {
+    const drafts = setDraft(new Map(), TRIP_A, { text: 'hello', files: [] })
+
+    expect(getDraft(drafts, TRIP_A).text).toBe('hello')
+    expect(getDraft(drafts, TRIP_B).text).toBe('')
+    expect(getDraft(drafts, INVOICE_A).text).toBe('')
+  })
+
+  it('is immutable and survives navigating away and back', () => {
+    const original = new Map()
+    const file = new File(['x'], 'a.png', { type: 'image/png' })
+    const withDraft = setDraft(original, TRIP_A, { text: 'hello', files: [file] })
+    const afterVisitingB = setDraft(withDraft, TRIP_B, { text: 'other', files: [] })
+
+    expect(original.size).toBe(0)
+    expect(withDraft).not.toBe(afterVisitingB)
+    expect(getDraft(afterVisitingB, TRIP_A)).toEqual({ text: 'hello', files: [file] })
+    expect(getDraft(withDraft, TRIP_B).text).toBe('')
+  })
+
+  it('clears only the sent subject', () => {
+    const both = setDraft(setDraft(new Map(), TRIP_A, { text: 'a', files: [] }), TRIP_B, { text: 'b', files: [] })
+    const cleared = clearDraft(both, TRIP_A)
+
+    expect(getDraft(cleared, TRIP_A).text).toBe('')
+    expect(getDraft(cleared, TRIP_B).text).toBe('b')
+    expect(getDraft(both, TRIP_A).text).toBe('a')
+  })
+
+  it('taking the draft for a send clears the field at once and returns trimmed text and files', () => {
+    const file = new File(['x'], 'a.png')
+    const drafts = setDraft(new Map(), TRIP_A, { text: ' hello ', files: [file] })
+    const taken = takeDraftForSend(drafts, TRIP_A)
+
+    expect(taken.content).toEqual({ text: 'hello', files: [file] })
+    expect(getDraft(taken.drafts, TRIP_A)).toEqual({ text: '', files: [] })
+    expect(getDraft(drafts, TRIP_A).text).toBe(' hello ')
+  })
+
+  it('text typed after the tap belongs to the next send, never to the one in flight', () => {
+    const first = takeDraftForSend(setDraft(new Map(), TRIP_A, { text: 'one', files: [] }), TRIP_A)
+    const typed = setDraft(first.drafts, TRIP_A, { text: 'two', files: [] })
+
+    expect(takeDraftForSend(typed, TRIP_A).content).toEqual({ text: 'two' })
+  })
+})

package/src/participant/participantDrafts.ts

@@ -0,0 +1,50 @@
+import type { ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+export type ParticipantDraft = {
+  readonly text: string
+  readonly files: readonly File[]
+}
+
+export type ParticipantDrafts = ReadonlyMap<string, ParticipantDraft>
+
+export const EMPTY_PARTICIPANT_DRAFT: ParticipantDraft = { text: '', files: [] }
+
+export function draftKey(subject: ParticipantSubjectRef): string {
+  return `${subject.subjectType}:${subject.subjectId}`
+}
+
+export function getDraft(drafts: ParticipantDrafts, subject: ParticipantSubjectRef): ParticipantDraft {
+  return drafts.get(draftKey(subject)) ?? EMPTY_PARTICIPANT_DRAFT
+}
+
+export function setDraft(drafts: ParticipantDrafts, subject: ParticipantSubjectRef, draft: ParticipantDraft): ParticipantDrafts {
+  return new Map(drafts).set(draftKey(subject), draft)
+}
+
+export function clearDraft(drafts: ParticipantDrafts, subject: ParticipantSubjectRef): ParticipantDrafts {
+  const next = new Map(drafts)
+  next.delete(draftKey(subject))
+  return next
+}
+
+export type ParticipantSendContent = {
+  readonly text?: string
+  readonly files?: readonly File[]
+}
+
+export type TakeDraftForSendResult = {
+  readonly drafts: ParticipantDrafts
+  /** Undefined when there was nothing to send, so a second tap on send does nothing. */
+  readonly content?: ParticipantSendContent
+}
+
+/** The field is cleared the instant the user taps send; the bubble becomes the owner of the content. */
+export function takeDraftForSend(drafts: ParticipantDrafts, subject: ParticipantSubjectRef): TakeDraftForSendResult {
+  const draft = getDraft(drafts, subject)
+  const text = draft.text.trim()
+  if (!text && draft.files.length === 0) return { drafts }
+  return {
+    drafts: clearDraft(drafts, subject),
+    content: { ...(text ? { text } : {}), ...(draft.files.length > 0 ? { files: draft.files } : {}) },
+  }
+}