# Timeline

O que aconteceu com uma coisa, em ordem.

Uma nota fiscal olha para trás (emitida, autorizada, enviada, paga, cancelada)
com carimbo de tempo e autor em cada ponto. Trilha de auditoria tem a mesma
forma: o que mudou, quando e por quem.

Sai como `<ol>` porque a ordem é o dado. Um leitor de tela que anuncia "lista de
5 itens" na ordem certa já entregou metade do que a linha desenha.

O tom é por item, de propósito: numa nota, a linha do cancelamento é vermelha e
as outras não, e é essa linha que a pessoa procura quando abre a trilha.
`pending` deixa o marcador vazado: preencher o marcador de um evento futuro
faz a linha prometer que ele já ocorreu, que é o erro que uma trilha de
auditoria não pode cometer.

## Movimento

Cada `TimelineItem` entra esmaecendo e subindo 4px (`animate-enter`, `--rc-duration-base`), sem escalonar: na montagem a trilha inteira entra de uma vez, e depois só o evento novo entra. Com "reduzir movimento", aparece parada.

## Quando não usar

Para um formulário longo em etapas, use `Steps`. O `Steps` é assistente: olha
para a frente, sabe quantos passos faltam e só deixa voltar. A `Timeline` olha
para trás e ninguém "avança" nela. Trocar uma pela outra faz o controle
prometer o que ele não faz, o mesmo argumento que separa `Progress` de `Meter`.

## As partes

`TimelineItem` é um ponto: `title`, `at`, `by`, `tone`, `pending`, e conteúdo
livre como filho. O `at` costuma receber um `RelativeTime`.

## No React Native

Traduz, com a lista por `items`: cada evento leva `title`, `at`, `by`, `description`, `tone` e `pending`, e a composição do `TimelineItem` não atravessa (a mesma regra do `RadioGroup` e do `Select`). **O carimbo é texto, e não um `RelativeTime`**: cada evento é uma parada só do leitor de tela e o rótulo dela é montado a partir desse texto, então um relógio vivo lá dentro continuaria andando na tela enquanto o rótulo ficaria preso na hora em que montou. E trilha de auditoria não pode dizer duas horas diferentes. Para o carimbo, `formatDate`. **A ordem, que o `<ol>` do web entrega de graça, vai escrita**: não existe papel de item de lista no React Native, então cada evento anuncia "3 de 5: Nota autorizada, 12/03 às 14:22, por Ana Duarte", uma frase com o que mudou, quando e por quem, em vez de três paradas de VoiceOver que não dizem o assunto. E nada é tocável: uma trilha se lê, e o marcador de 9px nunca seria alvo de dedo. Quem quer abrir o detalhe de um evento põe um `Item` com `onPress`.

## Importação

```tsx
import { Timeline } from '@rivocode/ui'
```

## Exemplos

### Trilha de uma nota

```tsx
import { RelativeTime, Timeline, TimelineItem } from '@rivocode/ui'

const AGORA = new Date('2026-08-25T18:00:00Z')

export function InvoiceTrail() {
  return (
    <div className="w-96">
      <Timeline>
        <TimelineItem
          title="Emitida"
          tone="accent"
          by="Ana Prado"
          at={<RelativeTime value={new Date('2026-08-25T12:04:00Z')} now={AGORA} />}
        />
        <TimelineItem
          title="Autorizada pela prefeitura"
          tone="success"
          at={<RelativeTime value={new Date('2026-08-25T12:05:00Z')} now={AGORA} />}
        >
          Protocolo 2026.4813.99
        </TimelineItem>
        <TimelineItem
          title="Cancelada"
          tone="danger"
          by="Carlos Nunes"
          at={<RelativeTime value={new Date('2026-08-25T14:20:00Z')} now={AGORA} />}
        >
          Motivo: dados do destinatário incorretos
        </TimelineItem>
        <TimelineItem title="Substituição pendente" pending />
      </Timeline>
    </div>
  )
}
```

## Props

Não tem prop própria. Repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [Code](/componentes/code.md)
- [EventCalendar](/componentes/event-calendar.md)
- [RelativeTime](/componentes/relative-time.md)
- [Tracker](/componentes/tracker.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)