# ShimmerText

A frase de espera que brilha: "Pensando…" enquanto o assistente ainda não
mandou o primeiro pedaço da resposta, "Consultando as notas…" enquanto um passo
do agente roda. Um brilho passa da esquerda para a direita por cima do texto, e
o texto continua texto. Vive em `@rivocode/ui/ai`.

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

<ShimmerText>Consultando as notas de agosto…</ShimmerText>
```

A `Message` em `streaming` sem conteúdo já usa a peça, com "Pensando…"
(`labels.thinking` troca a frase). Quando o texto começa a chegar, a frase sai e
ficam os três pontos depois dele. Use o `ShimmerText` sozinho para a espera que
mora fora de uma mensagem: o passo do agente embaixo da conversa, a linha de
status de um painel que resume.

## O brilho e o contraste

O brilho é um gradiente recortado na letra (`background-clip: text`) que corre
de `fg-muted` para `fg` e volta para `fg-muted`. As duas pontas são tokens, e o
gradiente nunca passa por transparente: em todo instante, cada letra está em
`fg-muted` ou mais forte. O contraste mínimo é o de `fg-muted` sobre o fundo, o
mesmo do texto secundário da casa, e é ele que o `check:contrast` mede sobre a
página, o cartão e o balão da `Message`.

`duration` é quanto dura uma passada, em milissegundos (2000, sem a prop). O
corpo, o peso e o tamanho vêm de quem chama, por `className`.

```tsx
<ShimmerText duration={1400} className="text-sm font-medium">
  Emitindo a nota da Clínica São Lucas…
</ShimmerText>
```

## Movimento reduzido

Com `prefers-reduced-motion: reduce`, a peça para e fica em `fg-muted`, sem
gradiente: a frase continua dizendo que algo está acontecendo, sem nada
correndo na tela. A frase é o sinal; o brilho é só o enfeite.

## Leitor de tela

A peça é uma região viva educada, `role="status"`: o leitor de tela ouve a
frase quando ela aparece e a cada troca de texto ("Consultando as notas…"
virando "Emitindo a nota…"), na pausa da fala, sem interromper. O brilho é só
CSS, e não mexe no texto: ninguém ouve a frase de novo a cada passada.

`announce={false}` desliga, para quando quem anuncia a espera é o contexto. A
`Message` em `streaming` faz isso: ela já é `aria-busy` dentro do `role="log"`
da `Conversation`, e duas regiões vivas falando a mesma coisa repetem.

```tsx
<ShimmerText announce={false}>Pensando…</ShimmerText>
```

## Quando não usar

- **Tarefa com fim medido** é `Progress`: a barra anda e termina, e diz quanto
  falta. O `ShimmerText` não sabe quanto falta, só que ainda não acabou.
- **Bloco que ainda vai carregar** é `Skeleton`, que guarda a forma do que vem.
  A frase que brilha diz o que está acontecendo, e não o tamanho do resultado.
- **Botão que espera a requisição** é o `loading` do `Button`, que recusa o
  segundo clique. Frase brilhando ao lado de um botão ainda clicável promete
  uma espera que o botão não respeita.
- **Texto que importa ler** não brilha. O brilho atrai o olho a cada passada:
  reserve-o para a espera curta, e nunca para um título ou um valor.

## No React Native

Traduz, no caminho próprio `@rivocode/ui-native/ai`, com os mesmos `children` e `duration`, e a `Message` em `streaming` sem conteúdo usa a peça do mesmo jeito, com o mesmo `labels.thinking`.

**O brilho é um pulso, e não uma faixa.** O web recorta um gradiente na letra com `background-clip: text`; o React Native não tem isso, e fazer pedia o `@react-native-masked-view/masked-view` e um gradiente nativo, dois peers que o caminho de IA não cobra de ninguém. Aqui a cor do texto inteiro vai de `fg-muted` a `fg` e volta, pelo Reanimated, e `duration` é a volta inteira (2000 ms, sem a prop). As duas pontas são os mesmos tokens do web, então o contraste nunca fica abaixo do de `fg-muted`.

**Com movimento reduzido no sistema, o texto fica parado em `fg-muted`.** A peça ouve a mudança do ajuste com o app aberto, como o resto do pacote. `className` veste o corpo e o peso; a cor é da peça.

**A frase é anunciada, como o `role="status"` do web.** Ela fala quando aparece e quando o texto troca, nunca a cada pulso, e repetir a mesma frase não fala de novo: no Android pela região viva educada, no iOS pelo anúncio do sistema, o mesmo arranjo das outras peças que avisam. `announce={false}` cala, para o contexto que já anuncia, e é o que a `Message` passa, como no web.

## Importação

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

## Exemplos

### Frase de espera

```tsx
import { Message, ShimmerText } from '@rivocode/ui/ai'

export function Waiting() {
  return <ShimmerText>Consultando as notas de agosto…</ShimmerText>
}
```

### Na mensagem que ainda não chegou

```tsx
import { Message, ShimmerText } from '@rivocode/ui/ai'

export function InMessage() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-4">
      <Message role="user">Quanto faturei em agosto?</Message>
      <Message role="assistant" streaming />
    </div>
  )
}
```

### Passo do agente

```tsx
import { Message, ShimmerText } from '@rivocode/ui/ai'

export function AgentStep() {
  return (
    <ShimmerText duration={1400} className="text-sm font-medium">
      Emitindo a nota da Clínica São Lucas…
    </ShimmerText>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `announce` | `boolean` |  | `true` | - | Faz da frase uma regiao viva educada (`role="status"`): o leitor de tela a ouve quando ela aparece e a cada troca de texto - "Consultando as notas…" virando "Emitindo a nota…" -, e nunca a cada passada do brilho, que e so CSS. |
| `duration` | `number` |  |  | - | Quanto dura uma passada do brilho, da esquerda para a direita, em milissegundos. |

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)
- [PromptInput](/componentes/prompt-input.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)
