# Conversation

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

```tsx
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.

```tsx
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](/componentes/bacalhau) dá
para cada vazio.

```tsx
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`.

## Importação

```tsx
import { Conversation } from '@rivocode/ui/ai'
```

## Exemplos

### Com histórico

```tsx
import { Avatar } from '@rivocode/ui'
import { Conversation, Message, PromptInput } from '@rivocode/ui/ai'
import { MessageSquare } from 'lucide-react'
import { useState } from 'react'

type Turn = { id: number; role: 'user' | 'assistant'; text: string }

const HISTORY: Turn[] = [
  { id: 1, role: 'user', text: 'Quantos pedidos a loja teve em agosto?' },
  {
    id: 2,
    role: 'assistant',
    text: 'Em agosto foram 42 pedidos, somando R$ 48.200,00. Três ainda não foram entregues.',
  },
  { id: 3, role: 'user', text: 'Quais faltam entregar?' },
  {
    id: 4,
    role: 'assistant',
    text: '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.',
  },
  { id: 5, role: 'user', text: 'Qual chega primeiro?' },
  {
    id: 6,
    role: 'assistant',
    text: 'O da Renata Pires, na sexta-feira. Os outros dois chegam no dia 15.',
  },
]

export function WithHistory() {
  const [turns, setTurns] = useState(HISTORY)

  return (
    <div className="flex h-[28rem] w-full max-w-xl flex-col gap-3">
      <Conversation className="flex-1">
        {turns.map((turn) => (
          <Message
            key={turn.id}
            role={turn.role}
            avatar={turn.role === 'assistant' ? <Avatar size="sm" fallback="R" /> : undefined}
          >
            {turn.text}
          </Message>
        ))}
      </Conversation>
      <PromptInput
        onSubmit={(text) =>
          setTurns((current) => [...current, { id: current.length + 1, role: 'user', text }])
        }
      />
    </div>
  )
}
```

### Vazia, com sugestões

```tsx
import { Avatar } from '@rivocode/ui'
import { Conversation, Message, PromptInput } from '@rivocode/ui/ai'
import { MessageSquare } from 'lucide-react'
import { useState } from 'react'

export function EmptyWithSuggestions() {
  const [asked, setAsked] = useState<string | null>(null)

  return (
    <div className="flex h-80 w-full max-w-xl flex-col">
      <Conversation
        className="flex-1"
        empty={{
          icon: <MessageSquare />,
          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={setAsked}
      >
        {asked && <Message role="user">{asked}</Message>}
      </Conversation>
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `actionsRef` | `Ref<ConversationActions>` |  |  | - | Recebe o `scrollToMessage(id)`, que rola ate a `Message` com aquele `messageId`, poe o foco nela e a destaca por um instante. |
| `classNames` | `Partial<Record<"content" \| "empty" \| "scrollButton" \| "suggestions" \| "viewport", string>>` |  |  | - |  |
| `empty` | `{ title: ReactNode; description: ReactNode; icon?: ReactNode; illustration?: ReactNode; suggestions?: string[] \| undefined; }` |  |  | - | O que aparece quando ainda nao ha mensagem nenhuma. |
| `label` | `string` |  | `"Conversa"` | - | O nome da regiao para o leitor de tela. |
| `labels` | `Partial<ConversationLabels>` |  |  | - | Os textos da peca, para trocar o idioma: `scroll` e o botao que volta ao fim da conversa, "Ir para o fim" sem ele. |
| `onSuggestion` | `((suggestion: string) => void)` |  |  | - | Chamado com o texto da sugestao tocada. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [AILabel](/componentes/ai-label.md)
- [Message](/componentes/message.md)
- [MessageMedia](/componentes/message-media.md)
- [PromptInput](/componentes/prompt-input.md)
- [ShimmerText](/componentes/shimmer-text.md)
- [ToolCall](/componentes/tool-call.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
