Pular para o conteúdo
IA

Conversation

/componentes/conversation.mdmarkdown cru, para quem lê com agent em vez de olho

Com histórico

Quantos pedidos a loja teve em agosto?
R
Em agosto foram 42 pedidos, somando R$ 48.200,00. Três ainda não foram entregues.
Quais faltam entregar?
R
O 1.204 da Renata Pires, de R$ 3.400,00; o 1.211 do Otávio Brandão, de R$ 780,00; e o 1.215 da Lívia Matos, de R$ 1.150,00.
Qual chega primeiro?
R
O da Renata Pires, na sexta-feira. Os outros dois chegam no dia 15.
Enter envia, Shift+Enter quebra a linha.

Vazia, com sugestões

Pergunte sobre a sua loja

O assistente lê os pedidos e o estoque desta loja, e nada além deles.

Importar
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. A Conversation desenha 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. A Timeline olha para trás e não recebe nada novo enquanto a pessoa lê; a Conversation existe 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

PropTipoPadrão
actionsRef

Recebe 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
classNamesPartial<Record<"content" | "empty" | "scrollButton" | "suggestions" | "viewport", string>>sem padrão
empty

O que aparece quando ainda nao ha mensagem nenhuma.

{ title: ReactNode; description: ReactNode; icon?: ReactNode; illustration?: ReactNode; suggestions?: string[] | undefined; }sem padrão
label

O nome da regiao para o leitor de tela.

string"Conversa"
labels

Os 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
onSuggestion

Chamado 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.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.