# PromptInput

O campo onde a pessoa escreve para um assistente: cresce com o texto, envia no
Enter, quebra a linha no Shift+Enter e troca o botão de enviar pelo de parar
enquanto a resposta chega. Vive em `@rivocode/ui/ai`.

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

<PromptInput
  streaming={isStreaming}
  onSubmit={(text) => send(text)}
  onStop={() => stop()}
/>
```

A peça não conhece modelo, SDK nem rede. Ela entrega o texto no `onSubmit` e
recebe de volta o `streaming`; quem fala com o modelo é a sua tela, com o SDK
que ela já usa.

## Enviar, quebrar a linha e parar

- **Enter envia.** Com o campo vazio (só espaço conta como vazio), desabilitado
  ou em `streaming`, não envia nada.
- **Shift+Enter quebra a linha.** A dica está ligada ao campo por
  `aria-describedby`, então quem usa leitor de tela ouve as duas regras ao
  entrar nele.
- **Enter no meio de uma composição do teclado não envia.** Quem digita com
  acento morto ou com teclado de ideogramas confirma a letra com Enter, e
  mandar a mensagem pela metade ali é o defeito mais comum desse tipo de campo.
- **Em `streaming`, o botão vira o de parar**, com o nome "Parar resposta", e
  chama o `onStop`. O campo continua aceitando texto para a próxima pergunta:
  só o envio espera.
- **O foco não se perde quando o botão desabilita.** Quem aperta Enter no
  "Parar resposta", ou está nele quando a resposta termina, vê o botão voltar a
  ser o de enviar, desabilitado porque o campo está vazio. O foco volta para o
  campo, e não cai no começo da página a cada turno. O mesmo vale para quem
  envia pelo botão.

O campo cresce até `maxRows` linhas (8, sem a prop) e, dali em diante, rola por
dentro. A altura se refaz também quando a largura muda e quando a fonte da casa
termina de carregar: o texto de duas linhas não fica cortado no celular nem
depois de a janela encolher.

## Controlado ou não

Sem `value`, a peça guarda o texto e o limpa depois de enviar. Com `value` e
`onValueChange`, quem limpa é você, no `onSubmit`: é o que permite devolver o
texto ao campo quando o envio falha.

```tsx
const [text, setText] = useState('')

<PromptInput
  value={text}
  onValueChange={setText}
  onSubmit={async (value) => {
    setText('')
    const ok = await send(value)
    if (!ok) setText(value)
  }}
/>
```

## Anexos, ações e contador

`attachments` é o lugar acima do campo para o que já foi anexado: fichas,
miniaturas. `actions` é o canto esquerdo do rodapé, para anexar, escolher o
modelo ou ditar. A peça **não escolhe arquivo**: ela só reserva o lugar, e o
seletor é seu.

`showCount` mostra a contagem de caracteres, como `120/4000` quando há
`maxLength`. Ao bater no teto a contagem vai para o tom de perigo, e o campo
recusa o que passa dele. O contador está ligado ao campo por
`aria-describedby`, dito por extenso ("120 de 4000 caracteres"), e o teto é
avisado numa região viva ("Limite de 4000 caracteres atingido."): quem não vê a
cor fica sabendo por que a tecla parou de escrever.

```tsx
<PromptInput
  maxLength={4000}
  showCount
  attachments={<Badge>contrato-agosto.pdf</Badge>}
  actions={
    <IconButton label="Anexar arquivo" variant="ghost" size="sm">
      <Paperclip />
    </IconButton>
  }
/>
```

## Respondendo uma mensagem

`replyTo` põe a citação em cima do campo, com o autor em acento e o trecho em
duas linhas, do jeito que ela vai sair no topo do balão enviado. O campo passa
a ser descrito por ela ("Resposta a Marina Costa: …"), e `onCancelReply` liga
o xis "Cancelar resposta", que devolve o foco ao campo. A peça não guarda a
resposta: quem chamou limpa no `onSubmit` e no `onCancelReply`, e quem abre a
resposta é o `onReply` da `Message`.

```tsx
<PromptInput
  replyTo={replying}
  onCancelReply={() => setReplying(undefined)}
  onSubmit={(text) => {
    enviar(text, replying?.id)
    setReplying(undefined)
  }}
/>
```

## Ditado

`dictation` liga o botão de microfone ao lado do enviar. A fala vira texto pela
Web Speech API do próprio navegador, sem SDK, e entra no fim do que já está no
campo enquanto a pessoa fala; `dictationLang` troca a língua (`pt-BR`, sem a
prop). O texto ditado é texto comum: a pessoa revisa e envia, e nada sai
sozinho.

```tsx
<PromptInput dictation onSubmit={(text) => send(text)} />
```

**O botão só aparece onde a API existe.** Chrome, Edge e Safari têm; o
Firefox não, e lá o botão some em vez de aparecer quebrado. A peça só pergunta
depois de montar, então a página renderizada no servidor não muda ao hidratar.

**Desligado por padrão, de propósito.** No Chrome o áudio vai para o servidor
do Google transcrever, e quem decide se a sua tela pode mandar a voz da pessoa
para fora é você, e não a biblioteca.

Os quatro momentos:

- **Antes**: o microfone é um botão de alternar, "Ditar mensagem", com
  `aria-pressed="false"`.
- **Ouvindo**: o botão fica apertado (`aria-pressed="true"`, com borda), o
  rodapé mostra um ponto pulsando e "Ouvindo… Fale a mensagem.", e a mesma
  frase vai ao leitor de tela por uma região viva. Tocar de novo encerra.
  A pausa entre as frases não desliga o microfone: a escuta é contínua, e
  quando o navegador corta a sessão sozinho, uma nova continua do texto já
  ditado. Só para quando a pessoa toca no botão, quando há erro, ou quando
  uma sessão termina sem ouvir nada.
- **Deu certo**: o texto já está no campo, o foco volta para ele e o leitor
  ouve "Texto ditado inserido no campo."
- **Deu errado**: a frase sai no rodapé, no tom de perigo, e é anunciada. Uma
  para cada causa: permissão negada ao microfone, nenhuma fala reconhecida,
  nenhum microfone disponível, e o resto. Ela some quando a pessoa volta a
  digitar, e o texto que já estava no campo fica.

Com `maxLength`, a fala é cortada no teto, como o que se digita. `disabled`
trava o microfone e encerra o que estava ouvindo.

## Nomes

O campo se chama "Mensagem", o botão "Enviar mensagem" e o de parar "Parar
resposta". `label`, `labels.submit` e `labels.stop` trocam os três, para
outra língua ou para um assistente com nome próprio.

`labels` troca o que o leitor de tela ouve além dos nomes: `hint` (a dica do
teclado), `count` (função da contagem e do teto) e `limit` (o aviso do teto).
Do ditado: `dictate` (o nome do microfone), `listening`, `dictated`, e as
falhas `dictationDenied`, `dictationSilent`, `dictationUnavailable` e
`dictationFailed`. Da resposta: `cancelReply` (o nome do xis) e `quote` (a
função que monta o que se ouve da citação).

```tsx
<PromptInput
  label="Message"
  labels={{
    hint: 'Enter sends, Shift+Enter adds a line.',
    count: (count, max) => `${count} of ${max} characters`,
    limit: (max) => `${max} character limit reached.`,
  }}
/>
```

## Partes

`classNames` alcança `reply` (a fileira da citação com o xis), `attachments`, `textarea`, `footer`, `count`, `submit` (o
botão de enviar e o de parar, que ocupam o mesmo lugar), `dictation` (o
microfone) e `dictationStatus` (a frase de ouvindo ou de erro no rodapé).

## Quando não usar

- **Texto longo de formulário** é `Textarea`. O `Textarea` guarda uma
  observação, uma descrição de serviço, e é enviado junto com o resto do
  formulário; o `PromptInput` é uma conversa, e cada Enter é um envio. Um
  campo de observação que envia no Enter perde o texto da pessoa na primeira
  quebra de linha.
- **Busca** é `SearchInput`. Pergunta para um assistente e filtro de lista
  parecem a mesma caixa, mas a busca responde enquanto se digita e não tem
  botão de parar.

## No React Native

Traduz, no caminho próprio `@rivocode/ui-native/ai`, com os mesmos `streaming`, `onStop`, `attachments`, `actions`, `maxLength`, `showCount`, `labels` e os mesmos nomes acessíveis ("Mensagem", "Enviar mensagem", "Parar resposta").

**O contador chega pelo campo.** A dica (`labels.hint`) e a contagem por extenso (`labels.count`) vão no `accessibilityHint` do campo, e o número visível fica fora da árvore de acessibilidade. Ao bater no `maxLength`, o leitor de tela anuncia `labels.limit`, uma vez por chegada ao teto. A dica padrão fala da tecla de retorno, que aqui quebra a linha.

**É controlado.** `value` e `onValueChange` são obrigatórios, como todo campo do pacote, e quem limpa o campo depois do `onSubmit` é quem chamou.

**O envio é só pelo botão.** No teclado do celular, a tecla de retorno de um campo de várias linhas quebra a linha, e é isso que a pessoa espera dela; não há Shift para separar os dois gestos. O campo cresce até `maxRows` linhas (8, sem a prop, como no web) e rola por dentro.

**Esperando a resposta é `streaming`, e não `disabled`.** Em `streaming` o campo continua editável e o teclado fica aberto para a próxima pergunta; só o envio espera, e o botão vira o de parar - travado quando não há `onStop`. O `disabled` trava a peça inteira, como no web, e no iOS um campo que deixa de ser editável perde o foco e fecha o teclado: ligá-lo a cada envio derruba o teclado a cada mensagem.

**O ditado não porta, e não é fila: é decisão.** O teclado do iOS e o do Android já trazem o microfone de fábrica, que escreve em qualquer campo de texto, na língua do aparelho e com a permissão que o sistema já pediu. Um segundo microfone dentro do campo duplicaria o botão que a pessoa já conhece, e cobraria um módulo nativo de reconhecimento de fala que o caminho de IA não pede. Por isso não há `dictation`, `dictationLang`, nem os textos de ditado em `labels`.

**A resposta, como no web.** `replyTo` põe a citação em cima do campo e `onCancelReply` liga o xis "Cancelar resposta"; a citação entra também no `accessibilityHint` do campo, antes da dica, para quem chega ao campo pelo leitor de tela saber que está respondendo.

As partes vestem pelo mesmo `classNames` do web: `reply`, `attachments`, `textarea`, `footer`, `count` e `submit`, que veste também o botão de parar no lugar dele.

## Importação

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

## Exemplos

### Enviar e parar

```tsx
import { IconButton } from '@rivocode/ui'
import { PromptInput } from '@rivocode/ui/ai'
import { Paperclip } from 'lucide-react'
import { useState } from 'react'

export function SendAndStop() {
  const [streaming, setStreaming] = useState(false)

  return (
    <div className="w-full max-w-xl">
      <PromptInput
        placeholder="Pergunte sobre os pedidos desta loja"
        streaming={streaming}
        onSubmit={() => setStreaming(true)}
        onStop={() => setStreaming(false)}
      />
    </div>
  )
}
```

### Com anexo e contador

```tsx
import { IconButton } from '@rivocode/ui'
import { PromptInput } from '@rivocode/ui/ai'
import { Paperclip } from 'lucide-react'
import { useState } from 'react'

export function WithAttachmentAndCount() {
  return (
    <div className="w-full max-w-xl">
      <PromptInput
        defaultValue="Resuma o contrato em anexo em três linhas."
        maxLength={4000}
        showCount
        attachments={
          <span className="rounded-md border border-border bg-surface-raised px-2 py-1 text-xs text-fg-muted">
            contrato-agosto.pdf
          </span>
        }
        actions={
          <IconButton label="Anexar arquivo" variant="ghost" size="sm">
            <Paperclip />
          </IconButton>
        }
      />
    </div>
  )
}
```

### Desabilitado

```tsx
import { IconButton } from '@rivocode/ui'
import { PromptInput } from '@rivocode/ui/ai'
import { Paperclip } from 'lucide-react'
import { useState } from 'react'

export function Disabled() {
  return (
    <div className="w-full max-w-xl">
      <PromptInput disabled placeholder="O assistente está fora do ar até as 14h" />
    </div>
  )
}
```

### Com ditado

```tsx
import { IconButton } from '@rivocode/ui'
import { PromptInput } from '@rivocode/ui/ai'
import { Paperclip } from 'lucide-react'
import { useState } from 'react'

export function WithDictation() {
  return (
    <div className="w-full max-w-xl">
      <PromptInput dictation placeholder="Escreva ou dite a pergunta" />
    </div>
  )
}
```

### Respondendo uma mensagem

```tsx
import { IconButton } from '@rivocode/ui'
import { PromptInput } from '@rivocode/ui/ai'
import { Paperclip } from 'lucide-react'
import { useState } from 'react'

export function Replying() {
  const [replying, setReplying] = useState<{ author: string; text: string } | undefined>({
    author: 'Marina Costa',
    text: 'Consegue mandar a foto da fachada? Preciso dela antes da reunião das 16h.',
  })
  return (
    <div className="w-full max-w-xl">
      <PromptInput
        replyTo={replying}
        onCancelReply={() => setReplying(undefined)}
        onSubmit={() => setReplying(undefined)}
      />
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `actions` | `ReactNode` |  |  | - | Os botoes do rodape, a esquerda: anexar, escolher modelo. |
| `attachments` | `ReactNode` |  |  | - | Os anexos ja escolhidos, acima do campo: fichas, miniaturas. |
| `classNames` | `Partial<Record<"attachments" \| "count" \| "dictation" \| "dictationStatus" \| "footer" \| "reply" \| "submit" \| "textarea", string>>` |  |  | - |  |
| `defaultValue` | `string` |  | `""` | - | O texto inicial, quando a peca guarda o proprio estado. |
| `dictation` | `boolean` |  | `false` | - | Liga o botao de microfone, ao lado do enviar: a fala vira texto pela Web Speech API do navegador e entra no fim do campo, enquanto a pessoa fala. |
| `dictationLang` | `string` |  | `"pt-BR"` | - | A lingua da fala, no formato BCP 47. |
| `disabled` | `boolean` |  | `false` | - | Trava o campo e o envio. |
| `label` | `string` |  | `"Mensagem"` | - | O nome do campo para o leitor de tela. |
| `labels` | `Partial<PromptInputLabels>` |  |  | - | Os textos da peca, para trocar o idioma: `submit` e `stop` sao os nomes do botao de enviar e do de parar, `hint` a dica do teclado ligada ao campo, `count` o que se ouve do contador e `limit` o aviso ao bater no teto. |
| `maxLength` | `number` |  |  | - | O teto de caracteres. |
| `maxRows` | `number` |  | `8` | - | Quantas linhas o campo cresce antes de rolar por dentro. |
| `onCancelReply` | `(() => void)` |  |  | - | Liga o xis "Cancelar resposta" na citacao. |
| `onStop` | `(() => void)` |  |  | - | Chamado pelo botao de parar, que so existe em `streaming`. |
| `onSubmit` | `((value: string) => void)` |  |  | - | Chamado com o texto ao apertar Enter ou o botao de enviar. |
| `onValueChange` | `((value: string) => void)` |  |  | - | Chamado a cada tecla, com o texto inteiro. |
| `placeholder` | `string` |  | `"Escreva uma mensagem"` | - |  |
| `replyTo` | `MessageReply` |  |  | - | A mensagem que a pessoa esta respondendo: a citacao em cima do campo, com o autor e o trecho, como ela vai sair no topo do balao enviado. |
| `showCount` | `boolean` |  | `false` | - | Mostra a contagem de caracteres no rodape, como `120/4000` quando ha `maxLength`. |
| `streaming` | `boolean` |  | `false` | - | A resposta esta chegando: o botao de enviar vira o de parar, e Enter deixa de enviar. |
| `value` | `string` |  |  | - | O texto do campo, controlado. |

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

## Ver também

- [AILabel](/componentes/ai-label.md)
- [Conversation](/componentes/conversation.md)
- [Message](/componentes/message.md)
- [MessageMedia](/componentes/message-media.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)
