Conversation
Com histórico
Vazia, com sugestões
Pergunte sobre a sua loja
O assistente lê os pedidos e o estoque desta loja, e nada além deles.
import { Conversation } from '@rivocode/ui/ai'Quando usar
A lista rolável de mensagens de uma conversa com um assistente. Gruda no fim
enquanto o texto chega, para de grudar quando a pessoa rola para cima para
reler, e oferece o botão "Ir para o fim" para voltar. Vive em
@rivocode/ui/ai.
import { Conversation, Message, PromptInput } from '@rivocode/ui/ai'
<div className="flex h-[32rem] flex-col gap-3">
<Conversation className="flex-1">
{messages.map((message) => (
<Message key={message.id} role={message.role} streaming={message.streaming}>
{message.text}
</Message>
))}
</Conversation>
<PromptInput onSubmit={send} />
</div>
A altura é sua, por classe. A conversa rola dentro do espaço que o pai der; sem altura definida ela cresce com as mensagens e empurra a página, que é o contrário de uma conversa.
Grudar no fim, e soltar
Enquanto a pessoa está no fim, toda mudança de tamanho (mensagem nova, pedaço de texto novo, imagem que carregou) rola até o fim. Quando ela rola para cima, a conversa solta: o texto continua chegando embaixo e a leitura dela não pula. Aparece então o botão "Ir para o fim", que volta, gruda de novo e some.
A volta é suave, e vira salto quando o sistema pede menos movimento.
labels.scroll troca o texto do botão.
Ir até uma mensagem
Tocar na citação de uma resposta leva até a original. A Conversation acha a
Message pelo messageId, rola até ela, centrada, põe o foco nela e a pinta
em selected por um segundo e meio. Com movimento reduzido, a rolagem é seca
e a cor some sem transição. A conversa solta do fim, como se a pessoa tivesse
rolado, e o "Ir para o fim" aparece para voltar.
Para pular de fora, como depois de carregar o histórico em que a original
estava, passe o actionsRef e chame o scrollToMessage(id) dele. Ele devolve
false quando a mensagem não está na árvore, e aí nada rola.
const conversa = useRef<ConversationActions>(null)
async function irAte(id: string | undefined) {
if (!id || conversa.current?.scrollToMessage(id)) return
await carregarAte(id)
conversa.current?.scrollToMessage(id)
}
<Conversation actionsRef={conversa} className="h-[32rem]">
{mensagens.map((m) => (
<Message key={m.id} messageId={m.id} role={m.role} replyTo={m.replyTo} onReplyPress={irAte}>
{m.text}
</Message>
))}
</Conversation>
Para o leitor de tela
A área é uma região role="log" com aria-live="polite" e o nome "Conversa"
(ou o que label disser): mensagem nova é anunciada quando o leitor termina a
frase, e não no meio dela. Junto com o aria-busy da Message em
streaming, a resposta é lida inteira no fim, e não pedaço por pedaço.
A área recebe foco pelo teclado, para rolar com as setas.
Vazia
empty desenha o EmptyState da casa quando não há mensagem nenhuma. As
suggestions viram botões, e o toque entrega o texto ao onSuggestion. Sem
onSuggestion, as sugestões não aparecem: botão que não faz nada é pior que
nenhum.
Quando a conversa ocupa a página ou a seção, o vazio leva desenho:
empty.illustration recebe o mesmo que a illustration do EmptyState, e
vence o icon, que fica para o painel estreito. Em produto da RivoCode, o
desenho é o Bacalhau, na pose que a página dele dá
para cada vazio.
import { EmptyInbox } from '@rivocode/ui/illustrations'
<Conversation
empty={{
illustration: <EmptyInbox size="md" />,
title: 'Pergunte sobre a sua loja',
description: 'O assistente lê os pedidos e o estoque desta loja, e nada além deles.',
suggestions: ['Quantos pedidos tive em agosto?', 'Quais produtos estão acabando?'],
}}
onSuggestion={send}
/>
Partes
classNames alcança viewport (a área que rola), content (a coluna das
mensagens), empty, suggestions e scrollButton.
Quando não usar
- Lista longa de linhas iguais é
VirtualList. AConversationdesenha todas as mensagens, porque uma conversa tem dezenas e não milhares, e o que ela resolve é o grudar no fim. Um registro de dez mil eventos pede a lista virtualizada. - Histórico de acontecimentos em ordem é
Timeline. ATimelineolha para trás e não recebe nada novo enquanto a pessoa lê; aConversationexiste justamente para o que está chegando agora.
No React Native
Traduz, no caminho próprio @rivocode/ui-native/ai, sobre uma FlatList invertida: o fim da conversa é o começo da lista, então quem está lá continua lá quando o texto cresce, sem conta nenhuma. Rolar para cima mostra o mesmo botão "Ir para o fim", e a lista segura a posição de leitura enquanto a mensagem nova chega embaixo.
A tela sobe com o teclado, e não cada peça. Conversation e PromptInput dividem a mesma coluna, e cada uma subindo sozinha passaria uma por cima da outra; dentro de Sheet ou Dialog, que já descontam o teclado, subiria duas vezes. Quem sobe é a coluna das duas, com o useKeyboardPadding() da raiz do pacote: ele devolve o estilo animado que soma a altura do teclado ao pé, e vai no style da View animada do Reanimated que embrulha a Conversation e o PromptInput. Dentro de um SafeAreaView com edges={['bottom']}, passe a área segura ao hook (useKeyboardPadding({ bottomInset: insets.bottom })): a altura do teclado já cobre a faixa da barrinha, e sem o desconto sobra um vão entre o campo e o teclado.
A lista vem por items, como todo o pacote: renderItem desenha uma mensagem e keyExtractor dá a chave. A ordem é a do web (a mais nova por último), e a inversão é da peça. O empty com suggestions e o onSuggestion atravessam com os mesmos nomes.
A mensagem nova é anunciada, como no role="log" do web: no Android pela região viva, e no iOS pelo anúncio do sistema, uma vez por mensagem e só quando o streaming acaba. O texto dito é o texto solto que o renderItem devolve; quem desenha a mensagem por um componente próprio diz a frase em announcement, e null ali espera.
Ir até uma mensagem é pela chave. O actionsRef e o scrollToMessage(id) atravessam com os mesmos nomes, e o id é a chave do keyExtractor, e não um messageId. A lista rola com o scrollToIndex, centrada, sem animar com movimento reduzido, e a linha da original fica em selected por um segundo e meio, sem transição. A FlatList só monta o que está perto da tela: quando a original está longe, a lista pula pela altura média dos itens e tenta de novo uma vez. O foco do leitor de tela fica na citação.
As partes vestem pelo mesmo classNames do web: viewport na FlatList, content no contentContainerClassName dela, empty, suggestions e scrollButton.
API
| Prop | Tipo | Padrão |
|---|---|---|
actionsRefRecebe o `scrollToMessage(id)`, que rola ate a `Message` com aquele `messageId`, poe o foco nela e a destaca por um instante. | Ref<ConversationActions> | sem padrão |
classNames | Partial<Record<"content" | "empty" | "scrollButton" | "suggestions" | "viewport", string>> | sem padrão |
emptyO que aparece quando ainda nao ha mensagem nenhuma. | { title: ReactNode; description: ReactNode; icon?: ReactNode; illustration?: ReactNode; suggestions?: string[] | undefined; } | sem padrão |
labelO nome da regiao para o leitor de tela. | string | "Conversa" |
labelsOs textos da peca, para trocar o idioma: `scroll` e o botao que volta ao fim da conversa, "Ir para o fim" sem ele. | Partial<ConversationLabels> | sem padrão |
onSuggestionChamado com o texto da sugestao tocada. | ((suggestion: string) => void) | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.