@adatechnology/conversations-ui 0.4.2 → 0.6.0

package/src/participant/participantThreadState.ts

@@ -0,0 +1,59 @@
+import type { ParticipantMessage } from '@adatechnology/conversation-contracts'
+
+export type ParticipantThreadState = {
+  readonly status: 'idle' | 'loading' | 'ready' | 'error'
+  /** Ascending by createdAt. */
+  readonly messages: readonly ParticipantMessage[]
+  readonly hasMore: boolean
+  readonly error?: string
+}
+
+export type ParticipantThreadAction =
+  | { readonly type: 'reset' }
+  | { readonly type: 'started' }
+  | { readonly type: 'loaded'; readonly messages: readonly ParticipantMessage[]; readonly hasMore: boolean }
+  | { readonly type: 'olderLoaded'; readonly messages: readonly ParticipantMessage[]; readonly hasMore: boolean }
+  | { readonly type: 'failed'; readonly error: string }
+  | { readonly type: 'sendConfirmed'; readonly message: ParticipantMessage }
+
+export const INITIAL_PARTICIPANT_THREAD_STATE: ParticipantThreadState = {
+  status: 'idle',
+  messages: [],
+  hasMore: false,
+}
+
+function unionById(
+  current: readonly ParticipantMessage[],
+  incoming: readonly ParticipantMessage[],
+): readonly ParticipantMessage[] {
+  const byId = new Map(current.map((message) => [message.id, message]))
+  for (const message of incoming) byId.set(message.id, message)
+  return [...byId.values()].sort((left, right) => Date.parse(left.createdAt) - Date.parse(right.createdAt))
+}
+
+function mergeMessages(
+  state: ParticipantThreadState,
+  incoming: readonly ParticipantMessage[],
+  hasMore: boolean,
+): ParticipantThreadState {
+  const messages = unionById(state.messages, incoming)
+  const { error: _error, ...rest } = state
+  return { ...rest, status: 'ready', messages, hasMore }
+}
+
+export function participantThreadReducer(state: ParticipantThreadState, action: ParticipantThreadAction): ParticipantThreadState {
+  switch (action.type) {
+    case 'reset':
+      return INITIAL_PARTICIPANT_THREAD_STATE
+    case 'started':
+      return state.status === 'ready' ? state : { ...state, status: 'loading' }
+    case 'loaded':
+      return mergeMessages(state, action.messages, state.messages.length === 0 ? action.hasMore : state.hasMore)
+    case 'olderLoaded':
+      return mergeMessages(state, action.messages, action.hasMore)
+    case 'failed':
+      return { ...state, status: 'error', error: action.error }
+    case 'sendConfirmed':
+      return { ...state, messages: unionById(state.messages, [action.message]) }
+  }
+}

package/src/participant/shouldMarkRead.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'bun:test'
+
+import { shouldMarkParticipantRead } from './shouldMarkRead'
+
+const SUBJECT = { subjectType: 'trip', subjectId: 'a' }
+
+describe('shouldMarkParticipantRead', () => {
+  it('is true for the selected subject, visible, with unread messages', () => {
+    expect(shouldMarkParticipantRead({ selected: SUBJECT, subject: { ...SUBJECT }, visibilityState: 'visible', unreadCount: 2 })).toBe(true)
+  })
+  it('is false when nothing is selected', () => {
+    expect(shouldMarkParticipantRead({ selected: undefined, subject: SUBJECT, visibilityState: 'visible', unreadCount: 2 })).toBe(false)
+  })
+  it('is false when another subject is selected (id or type differs)', () => {
+    expect(shouldMarkParticipantRead({ selected: { subjectType: 'trip', subjectId: 'b' }, subject: SUBJECT, visibilityState: 'visible', unreadCount: 2 })).toBe(false)
+    expect(shouldMarkParticipantRead({ selected: { subjectType: 'invoice', subjectId: 'a' }, subject: SUBJECT, visibilityState: 'visible', unreadCount: 2 })).toBe(false)
+  })
+  it('is false while the document is hidden', () => {
+    expect(shouldMarkParticipantRead({ selected: SUBJECT, subject: SUBJECT, visibilityState: 'hidden', unreadCount: 2 })).toBe(false)
+  })
+  it('is false without unread messages', () => {
+    expect(shouldMarkParticipantRead({ selected: SUBJECT, subject: SUBJECT, visibilityState: 'visible', unreadCount: 0 })).toBe(false)
+  })
+})

package/src/participant/shouldMarkRead.ts

@@ -0,0 +1,16 @@
+import type { ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+export type ShouldMarkParticipantReadParams = {
+  readonly selected: ParticipantSubjectRef | undefined
+  readonly subject: ParticipantSubjectRef
+  readonly visibilityState: DocumentVisibilityState
+  readonly unreadCount: number
+}
+
+export function shouldMarkParticipantRead(params: ShouldMarkParticipantReadParams): boolean {
+  const { selected, subject, visibilityState, unreadCount } = params
+  if (!selected) return false
+  if (selected.subjectType !== subject.subjectType || selected.subjectId !== subject.subjectId) return false
+  if (visibilityState !== 'visible') return false
+  return unreadCount > 0
+}

package/src/participant/useDocumentVisibility.ts

@@ -0,0 +1,18 @@
+import { useEffect, useState } from 'react'
+
+export function useDocumentVisibility(): DocumentVisibilityState {
+  const [visibilityState, setVisibilityState] = useState<DocumentVisibilityState>(() =>
+    typeof document === 'undefined' ? 'visible' : document.visibilityState,
+  )
+
+  useEffect(() => {
+    function handleVisibilityChange(): void {
+      setVisibilityState(document.visibilityState)
+    }
+    handleVisibilityChange()
+    document.addEventListener('visibilitychange', handleVisibilityChange)
+    return () => document.removeEventListener('visibilitychange', handleVisibilityChange)
+  }, [])
+
+  return visibilityState
+}

package/src/participant/useParticipantConversationView.ts

@@ -0,0 +1,60 @@
+import { useCallback, useMemo, type Dispatch } from 'react'
+
+import type { ParticipantConversationSummary, ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+import type { ConversationChannel } from '../conversationChannel'
+import type { ParticipantConversationsApi, ParticipantPendingMessage } from './participantApi.types'
+import { mergeParticipantMessages, type ParticipantTimelineItem } from './participantMessages'
+import type { ParticipantSendAction, ParticipantSendEntry } from './participantSendController'
+import { selectSendEntries, type ParticipantSendStates, type ParticipantSendStatesAction } from './participantSendStates'
+import { useParticipantThread, type UseParticipantThreadResult } from './useParticipantThread'
+
+export type UseParticipantConversationViewParams = {
+  readonly api: ParticipantConversationsApi
+  readonly subject: ParticipantSubjectRef
+  readonly conversation: ParticipantConversationSummary
+  readonly channel?: ConversationChannel
+  readonly onMarkedRead: (subject: ParticipantSubjectRef) => void
+  readonly pendingMessages?: readonly ParticipantPendingMessage[]
+  readonly sendStates: ParticipantSendStates
+  readonly dispatchSendStates: Dispatch<ParticipantSendStatesAction>
+}
+
+export type UseParticipantConversationViewResult = {
+  readonly thread: UseParticipantThreadResult
+  readonly items: readonly ParticipantTimelineItem[]
+  readonly sendEntries: readonly ParticipantSendEntry[]
+  readonly dispatchSend: (action: ParticipantSendAction) => void
+}
+
+export function useParticipantConversationView(params: UseParticipantConversationViewParams): UseParticipantConversationViewResult {
+  const { api, subject, conversation, pendingMessages, sendStates, dispatchSendStates } = params
+  const { subjectType, subjectId } = subject
+  const sendEntries = selectSendEntries(sendStates, subject)
+  const dispatchSend = useCallback(
+    (action: ParticipantSendAction) => dispatchSendStates({ subject: { subjectType, subjectId }, action }),
+    [dispatchSendStates, subjectType, subjectId],
+  )
+  const thread = useParticipantThread({
+    api,
+    subject,
+    channel: params.channel,
+    unreadCount: conversation.unreadCount,
+    onMarkedRead: params.onMarkedRead,
+    sendEntries,
+    dispatchSend,
+    hostPending: pendingMessages,
+  })
+  const items = useMemo(
+    () =>
+      mergeParticipantMessages({
+        serverMessages: thread.messages,
+        hostPending: pendingMessages ?? [],
+        localPending: thread.localPending,
+        subject,
+      }),
+    [thread.messages, thread.localPending, pendingMessages, subject],
+  )
+
+  return { thread, items, sendEntries, dispatchSend }
+}

package/src/participant/useParticipantDraft.ts

@@ -0,0 +1,45 @@
+import { useState, type MutableRefObject } from 'react'
+
+import type { ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+import {
+  getDraft,
+  setDraft,
+  takeDraftForSend,
+  type ParticipantDraft,
+  type ParticipantDrafts,
+  type ParticipantSendContent,
+} from './participantDrafts'
+import { appendEntryToDraft, type ParticipantSendEntry } from './participantSendController'
+
+export type UseParticipantDraftResult = {
+  readonly draft: ParticipantDraft
+  readonly setText: (text: string) => void
+  readonly setFiles: (files: readonly File[]) => void
+  /** Clears the field synchronously and hands the content over; undefined when there is nothing to send. */
+  readonly takeForSend: () => ParticipantSendContent | undefined
+  readonly restoreFromEntry: (entry: ParticipantSendEntry) => void
+}
+
+/** The ref holds the truth (read at call time, so a double tap sees the cleared field); state only re-renders. */
+export function useParticipantDraft(draftsRef: MutableRefObject<ParticipantDrafts>, subject: ParticipantSubjectRef): UseParticipantDraftResult {
+  const [draft, setDraftState] = useState<ParticipantDraft>(() => getDraft(draftsRef.current, subject))
+
+  function replaceDrafts(next: ParticipantDrafts): void {
+    draftsRef.current = next
+    setDraftState(getDraft(next, subject))
+  }
+  function update(change: Partial<ParticipantDraft>): void {
+    replaceDrafts(setDraft(draftsRef.current, subject, { ...getDraft(draftsRef.current, subject), ...change }))
+  }
+  function takeForSend(): ParticipantSendContent | undefined {
+    const taken = takeDraftForSend(draftsRef.current, subject)
+    if (taken.content) replaceDrafts(taken.drafts)
+    return taken.content
+  }
+  function restoreFromEntry(entry: ParticipantSendEntry): void {
+    update(appendEntryToDraft(entry, getDraft(draftsRef.current, subject)))
+  }
+
+  return { draft, setText: (text) => update({ text }), setFiles: (files) => update({ files }), takeForSend, restoreFromEntry }
+}

package/src/participant/useParticipantInbox.ts

@@ -0,0 +1,57 @@
+import { useCallback, useEffect, useReducer } from 'react'
+
+import type { ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+import type { ParticipantConversationsApi } from './participantApi.types'
+import { INITIAL_PARTICIPANT_INBOX_STATE, participantInboxReducer, type ParticipantInboxState } from './participantInboxState'
+import { useParticipantRevalidation } from './useParticipantRevalidation'
+
+export type UseParticipantInboxResult = ParticipantInboxState & {
+  readonly hasMore: boolean
+  readonly refresh: () => Promise<void>
+  readonly loadMore: () => Promise<void>
+  readonly markSubjectRead: (subject: ParticipantSubjectRef) => void
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : 'unknown error'
+}
+
+export function useParticipantInbox(api: ParticipantConversationsApi): UseParticipantInboxResult {
+  const [state, dispatch] = useReducer(participantInboxReducer, INITIAL_PARTICIPANT_INBOX_STATE)
+
+  const refresh = useCallback(async (): Promise<void> => {
+    dispatch({ type: 'started' })
+    try {
+      const page = await api.listConversations()
+      dispatch({ type: 'loaded', conversations: page.data, ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}) })
+    } catch (error) {
+      dispatch({ type: 'failed', error: describeError(error) })
+    }
+  }, [api])
+
+  const { nextCursor } = state
+  const loadMore = useCallback(async (): Promise<void> => {
+    if (!nextCursor) return
+    try {
+      const page = await api.listConversations({ cursor: nextCursor })
+      dispatch({ type: 'appended', conversations: page.data, ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}) })
+    } catch (error) {
+      dispatch({ type: 'failed', error: describeError(error) })
+    }
+  }, [api, nextCursor])
+
+  const markSubjectRead = useCallback((subject: ParticipantSubjectRef): void => {
+    dispatch({ type: 'markedRead', subject })
+  }, [])
+
+  useEffect(() => {
+    void refresh()
+  }, [refresh])
+
+  useParticipantRevalidation(api, () => {
+    void refresh()
+  })
+
+  return { ...state, hasMore: nextCursor !== undefined, refresh, loadMore, markSubjectRead }
+}

package/src/participant/useParticipantMarkRead.ts

@@ -0,0 +1,26 @@
+import { useEffect, type MutableRefObject } from 'react'
+
+import type { ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+import type { ParticipantConversationsApi } from './participantApi.types'
+import { shouldMarkParticipantRead } from './shouldMarkRead'
+import { useDocumentVisibility } from './useDocumentVisibility'
+
+export type UseParticipantMarkReadParams = {
+  readonly apiRef: MutableRefObject<ParticipantConversationsApi>
+  readonly subject: ParticipantSubjectRef
+  readonly unreadCount: number
+  /** Marking again when a message arrives while the screen stays open. */
+  readonly messageCount: number
+  readonly onMarkedRead?: (subject: ParticipantSubjectRef) => void
+}
+
+export function useParticipantMarkRead(params: UseParticipantMarkReadParams): void {
+  const { apiRef, subject, unreadCount, messageCount, onMarkedRead } = params
+  const visibilityState = useDocumentVisibility()
+
+  useEffect(() => {
+    if (!shouldMarkParticipantRead({ selected: subject, subject, visibilityState, unreadCount })) return
+    void apiRef.current.markRead(subject).then(() => onMarkedRead?.(subject), () => undefined)
+  }, [apiRef, subject, visibilityState, unreadCount, messageCount, onMarkedRead])
+}

package/src/participant/useParticipantRevalidation.ts

@@ -0,0 +1,36 @@
+import { useEffect, useRef } from 'react'
+
+import type { ParticipantConversationEvent, ParticipantConversationsApi } from './participantApi.types'
+
+type RevalidationHandler = (event?: ParticipantConversationEvent) => void
+
+/** Subscribes to the host when it can push events (still revalidating on reconnection, when an event may have been lost); otherwise also on focus and visibility. */
+export function useParticipantRevalidation(api: ParticipantConversationsApi, onRevalidate: RevalidationHandler): void {
+  const handlerRef = useRef(onRevalidate)
+  handlerRef.current = onRevalidate
+
+  useEffect(() => {
+    function handleFocus(): void {
+      handlerRef.current()
+    }
+    if (api.subscribe) {
+      const unsubscribe = api.subscribe((event) => handlerRef.current(event))
+      window.addEventListener('online', handleFocus)
+      return () => {
+        unsubscribe()
+        window.removeEventListener('online', handleFocus)
+      }
+    }
+    function handleVisibilityChange(): void {
+      if (document.visibilityState === 'visible') handlerRef.current()
+    }
+    window.addEventListener('focus', handleFocus)
+    window.addEventListener('online', handleFocus)
+    document.addEventListener('visibilitychange', handleVisibilityChange)
+    return () => {
+      window.removeEventListener('focus', handleFocus)
+      window.removeEventListener('online', handleFocus)
+      document.removeEventListener('visibilitychange', handleVisibilityChange)
+    }
+  }, [api])
+}

package/src/participant/useParticipantSend.ts

@@ -0,0 +1,84 @@
+import { useCallback, useRef, type MutableRefObject } from 'react'
+
+import type { ParticipantMessage, ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+import type { ParticipantConversationsApi } from './participantApi.types'
+import type { ParticipantSendContent } from './participantDrafts'
+import {
+  createParticipantSendEntry,
+  findFailedEntry,
+  type ParticipantSendAction,
+  type ParticipantSendEntry,
+} from './participantSendController'
+
+export type ParticipantSendOutcome = 'sent' | 'queued' | 'failed'
+
+export type UseParticipantSendParams = {
+  readonly apiRef: MutableRefObject<ParticipantConversationsApi>
+  readonly subject: ParticipantSubjectRef
+  readonly entries: readonly ParticipantSendEntry[]
+  readonly dispatchSend: (action: ParticipantSendAction) => void
+  readonly onSentMessage: (message: ParticipantMessage) => void
+}
+
+export type UseParticipantSendResult = {
+  readonly send: (content: ParticipantSendContent) => Promise<ParticipantSendOutcome>
+  readonly retry: (clientMessageId: string) => Promise<void>
+}
+
+export function useParticipantSend(params: UseParticipantSendParams): UseParticipantSendResult {
+  const { apiRef, subject, dispatchSend, onSentMessage } = params
+  const entriesRef = useRef(params.entries)
+  entriesRef.current = params.entries
+
+  const deliver = useCallback(
+    async (entry: ParticipantSendEntry): Promise<ParticipantSendOutcome> => {
+      const { clientMessageId } = entry
+      try {
+        const result = await apiRef.current.sendMessage({
+          subject: entry.subject,
+          clientMessageId,
+          ...(entry.text ? { text: entry.text } : {}),
+          ...(entry.files.length > 0 ? { files: entry.files } : {}),
+        })
+        if (result.outcome === 'sent') {
+          onSentMessage(result.message)
+          dispatchSend({ type: 'sent', clientMessageId, message: result.message })
+          return 'sent'
+        }
+        dispatchSend({ type: 'queued', clientMessageId })
+        return 'queued'
+      } catch {
+        dispatchSend({ type: 'failed', clientMessageId })
+        return 'failed'
+      }
+    },
+    [apiRef, dispatchSend, onSentMessage],
+  )
+
+  const send = useCallback(
+    async (content: ParticipantSendContent): Promise<ParticipantSendOutcome> => {
+      const entry = createParticipantSendEntry({
+        clientMessageId: crypto.randomUUID(),
+        subject,
+        content,
+        createdAt: new Date().toISOString(),
+      })
+      dispatchSend({ type: 'started', entry })
+      return deliver(entry)
+    },
+    [deliver, dispatchSend, subject],
+  )
+
+  const retry = useCallback(
+    async (clientMessageId: string): Promise<void> => {
+      const entry = findFailedEntry(entriesRef.current, clientMessageId)
+      if (!entry) return
+      dispatchSend({ type: 'retried', clientMessageId })
+      await deliver({ ...entry, state: 'sending' })
+    },
+    [deliver, dispatchSend],
+  )
+
+  return { send, retry }
+}

package/src/participant/useParticipantThread.ts

@@ -0,0 +1,116 @@
+import { useCallback, useEffect, useMemo, useReducer, useRef } from 'react'
+
+import type { ParticipantMessage, ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+import { channelCapabilityFor } from '../channelCapability'
+import type { ConversationChannel } from '../conversationChannel'
+import type {
+  ParticipantConversationEvent,
+  ParticipantConversationsApi,
+  ParticipantLocalPendingMessage,
+  ParticipantPendingMessage,
+} from './participantApi.types'
+import {
+  collectKnownClientMessageIds,
+  toLocalPending,
+  type ParticipantSendAction,
+  type ParticipantSendEntry,
+} from './participantSendController'
+import { INITIAL_PARTICIPANT_THREAD_STATE, participantThreadReducer, type ParticipantThreadState } from './participantThreadState'
+import { useParticipantMarkRead } from './useParticipantMarkRead'
+import { useParticipantRevalidation } from './useParticipantRevalidation'
+import { useParticipantSend, type UseParticipantSendResult } from './useParticipantSend'
+
+const THREAD_PAGE_SIZE = 30
+
+export type UseParticipantThreadParams = {
+  /** Keep it stable: a new identity re-subscribes to events (it never resets the conversation). */
+  readonly api: ParticipantConversationsApi
+  readonly subject: ParticipantSubjectRef
+  readonly channel?: ConversationChannel
+  /** Unread count of this subject as the inbox knows it; drives markRead. */
+  readonly unreadCount?: number
+  readonly onMarkedRead?: (subject: ParticipantSubjectRef) => void
+  /** Sends of this subject, owned above the conversation so they survive leaving it. */
+  readonly sendEntries: readonly ParticipantSendEntry[]
+  readonly dispatchSend: (action: ParticipantSendAction) => void
+  readonly hostPending?: readonly ParticipantPendingMessage[]
+}
+
+export type UseParticipantThreadResult = ParticipantThreadState &
+  UseParticipantSendResult & {
+    readonly confirmsRead: boolean
+    readonly localPending: readonly ParticipantLocalPendingMessage[]
+    readonly refresh: () => Promise<void>
+    readonly loadOlder: () => Promise<void>
+  }
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : 'unknown error'
+}
+
+function isForSubject(event: ParticipantConversationEvent | undefined, subject: ParticipantSubjectRef): boolean {
+  if (!event || event.type === 'inbox-changed') return true
+  return event.subject.subjectType === subject.subjectType && event.subject.subjectId === subject.subjectId
+}
+
+export function useParticipantThread(params: UseParticipantThreadParams): UseParticipantThreadResult {
+  const { api, subject, channel, unreadCount = 0, onMarkedRead, sendEntries, dispatchSend, hostPending = [] } = params
+  const { subjectType, subjectId } = subject
+  const stableSubject = useMemo<ParticipantSubjectRef>(() => ({ subjectType, subjectId }), [subjectType, subjectId])
+  const [state, dispatch] = useReducer(participantThreadReducer, INITIAL_PARTICIPANT_THREAD_STATE)
+  const apiRef = useRef(api)
+  apiRef.current = api
+  const activeSubjectKey = useRef('')
+  const confirmsRead = channelCapabilityFor(channel).confirmsRead
+
+  const refresh = useCallback(async (): Promise<void> => {
+    const requestKey = `${subjectType}:${subjectId}`
+    dispatch({ type: 'started' })
+    try {
+      const messages = await apiRef.current.fetchMessages(stableSubject, { limit: THREAD_PAGE_SIZE })
+      if (activeSubjectKey.current === requestKey) {
+        dispatch({ type: 'loaded', messages, hasMore: messages.length >= THREAD_PAGE_SIZE })
+      }
+    } catch (error) {
+      if (activeSubjectKey.current === requestKey) dispatch({ type: 'failed', error: describeError(error) })
+    }
+  }, [stableSubject, subjectType, subjectId])
+
+  const oldestMessageId = state.messages[0]?.id
+  const loadOlder = useCallback(async (): Promise<void> => {
+    if (!oldestMessageId) return
+    const requestKey = `${subjectType}:${subjectId}`
+    try {
+      const messages = await apiRef.current.fetchMessages(stableSubject, { before: oldestMessageId, limit: THREAD_PAGE_SIZE })
+      if (activeSubjectKey.current === requestKey) {
+        dispatch({ type: 'olderLoaded', messages, hasMore: messages.length >= THREAD_PAGE_SIZE })
+      }
+    } catch (error) {
+      if (activeSubjectKey.current === requestKey) dispatch({ type: 'failed', error: describeError(error) })
+    }
+  }, [stableSubject, subjectType, subjectId, oldestMessageId])
+
+  const handleSentMessage = useCallback((message: ParticipantMessage) => dispatch({ type: 'sendConfirmed', message }), [])
+  const sending = useParticipantSend({ apiRef, subject: stableSubject, entries: sendEntries, dispatchSend, onSentMessage: handleSentMessage })
+
+  useEffect(() => {
+    activeSubjectKey.current = `${subjectType}:${subjectId}`
+    dispatch({ type: 'reset' })
+    void refresh()
+  }, [refresh, subjectType, subjectId])
+
+  useParticipantRevalidation(api, (event) => {
+    if (isForSubject(event, stableSubject)) void refresh()
+  })
+
+  useEffect(() => {
+    if (sendEntries.length === 0) return
+    dispatchSend({ type: 'reflected', knownClientMessageIds: collectKnownClientMessageIds({ messages: state.messages, hostPending }) })
+  }, [sendEntries, state.messages, hostPending, dispatchSend])
+
+  useParticipantMarkRead({ apiRef, subject: stableSubject, unreadCount, messageCount: state.messages.length, onMarkedRead })
+
+  const localPending = useMemo(() => toLocalPending(sendEntries), [sendEntries])
+  return { ...state, localPending, confirmsRead, refresh, loadOlder, ...sending }
+}

package/src/participant/useParticipantThreadScroll.ts

@@ -0,0 +1,26 @@
+import { useEffect, useRef } from 'react'
+
+import { collectServerMessageIds, countNewIncomingMessages } from './participantNewMessages'
+import type { ParticipantTimelineItem } from './participantMessages'
+import { useStickToBottom, type ParticipantThreadScroll } from './useStickToBottom'
+
+export type UseParticipantThreadScrollResult = {
+  readonly scroll: ParticipantThreadScroll
+  readonly newMessagesCount: number
+}
+
+function keyOf(item: ParticipantTimelineItem | undefined): string | undefined {
+  if (!item) return 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]) })
+  const seenIds = useRef<ReadonlySet<string>>(new Set())
+
+  useEffect(() => {
+    if (isNearBottom) seenIds.current = collectServerMessageIds(items)
+  }, [isNearBottom, items])
+
+  return { scroll, newMessagesCount: isNearBottom ? 0 : countNewIncomingMessages(seenIds.current, items) }
+}

package/src/participant/useStickToBottom.ts

@@ -0,0 +1,77 @@
+import { useCallback, useLayoutEffect, useRef, useState, type RefObject, type UIEvent } from 'react'
+
+import { NEAR_BOTTOM_THRESHOLD_PX, resolveScrollAction, scrollAnchorAfterPrepend, shouldStickToBottom } from './participantScroll'
+
+export type UseStickToBottomParams = {
+  readonly firstKey: string | undefined
+  readonly lastKey: string | undefined
+}
+
+export type ParticipantThreadScroll = {
+  readonly ref: RefObject<HTMLDivElement | null>
+  readonly onScroll: (event: UIEvent<HTMLDivElement>) => void
+}
+
+export type UseStickToBottomResult = {
+  readonly scroll: ParticipantThreadScroll
+  readonly isNearBottom: boolean
+}
+
+type Snapshot = {
+  hasPositioned: boolean
+  firstKey: string | undefined
+  lastKey: string | undefined
+  scrollTop: number
+  scrollHeight: number
+}
+
+export function useStickToBottom({ firstKey, lastKey }: UseStickToBottomParams): UseStickToBottomResult {
+  const ref = useRef<HTMLDivElement | null>(null)
+  const snapshot = useRef<Snapshot>({ hasPositioned: false, firstKey: undefined, lastKey: undefined, scrollTop: 0, scrollHeight: 0 })
+  const [isNearBottom, setIsNearBottom] = useState(true)
+  const isNearBottomRef = useRef(true)
+
+  const onScroll = useCallback((event: UIEvent<HTMLDivElement>): void => {
+    const { scrollTop, clientHeight, scrollHeight } = event.currentTarget
+    const isNear = shouldStickToBottom({ scrollTop, clientHeight, scrollHeight, threshold: NEAR_BOTTOM_THRESHOLD_PX })
+    snapshot.current.scrollTop = scrollTop
+    snapshot.current.scrollHeight = scrollHeight
+    isNearBottomRef.current = isNear
+    setIsNearBottom(isNear)
+  }, [])
+
+  useLayoutEffect(() => {
+    const element = ref.current
+    const previous = snapshot.current
+    if (!element) return
+    const action = resolveScrollAction({
+      hasPositioned: previous.hasPositioned,
+      previousFirstKey: previous.firstKey,
+      previousLastKey: previous.lastKey,
+      firstKey,
+      lastKey,
+      wasNearBottom: isNearBottomRef.current,
+    })
+    if (action === 'bottom') {
+      element.scrollTop = element.scrollHeight
+      isNearBottomRef.current = true
+      setIsNearBottom(true)
+    }
+    if (action === 'anchor') {
+      element.scrollTop = scrollAnchorAfterPrepend({
+        previousScrollTop: previous.scrollTop,
+        previousScrollHeight: previous.scrollHeight,
+        scrollHeight: element.scrollHeight,
+      })
+    }
+    snapshot.current = {
+      hasPositioned: previous.hasPositioned || action === 'bottom',
+      firstKey,
+      lastKey,
+      scrollTop: element.scrollTop,
+      scrollHeight: element.scrollHeight,
+    }
+  }, [firstKey, lastKey])
+
+  return { scroll: { ref, onScroll }, isNearBottom }
+}

package/src/preview/ConversationSimulatorPanel.tsx

@@ -62,6 +62,14 @@ const SIMULATOR_PANEL_CHANNEL_WORDING: Readonly<Record<ConversationChannel, Chan
     destinationHint: DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS.destinationHint,
     placeholder: DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS.placeholder,
   },
+  [CONVERSATION_CHANNEL.APP]: {
+    destinationHint: 'entrega no app do contratante',
+    placeholder: 'Escreva como quem usa o app…',
+  },
+  [CONVERSATION_CHANNEL.PORTAL]: {
+    destinationHint: 'entrega no portal do contratante',
+    placeholder: 'Escreva como quem usa o portal…',
+  },
   [CONVERSATION_CHANNEL.WEBCHAT]: {
     destinationHint: 'entrega na API do chat do site',
     placeholder: 'Escreva como o visitante…',