Timeline

Linha do tempo de leitura: Marcos, eventos e histórico em ordem.

A Timeline (do HeroUI Pro) mostra uma cronologia só de leitura: os Marcos da Jornada de um Pedido, o registro de eventos, a história de versões. Se a pessoa avança por etapas conhecidas, use Stepper. O estado é sempre dito em texto, nunca só pela cor do marcador.

import { Timeline } from "@rastreio-x/ui";

Padrão

Cada Timeline.Item tem status, um trilho (Timeline.Rail) com marcador e conector, e um Timeline.Content. Os ícones dos marcadores são decorativos.

Pedido Recebido
08/10, 14:20
Em Trânsito
09/10, 09:05
Saiu para Entrega
previsto 16/10
Entregue
previsto 17/10

Status

Seis tons de marcador: default, current, success, warning, danger e muted. O item current ganha aria-current.

Padrão (status “default”)
Atual (status “current”)
Concluído (status “success”)
Atrasado (status “warning”)
Falhou (status “danger”)
Pendente (status “muted”)

Registro compacto

density="compact" e size="sm" formam um registro denso de eventos, com horário e uma linha de contexto.

Pedido aceito14:20
Webhook da Fonte Checkout Yampi
Jornada publicada14:20
Template Padrão, versão 3
Mapa do destinoEm andamento14:21
Geocodificação em andamento
E-mail ao Cliente14:22
Aguardando o aviso de Pedido Recebido

Atrasado

Atrasado combina marcador de aviso, a palavra visível e o texto para o leitor de tela.

Em Trânsito
05/10, 08:40
Saiu para Entrega — atrasadoAtrasado
previsto para 12/10

Anatomia

Timeline
├── Timeline.Connector
├── Timeline.Content
├── Timeline.Item
├── Timeline.Marker
└── Timeline.Rail

Timeline.Item: um evento, com status.
Timeline.Rail: agrupa marcador e conector.
Timeline.Marker: o marcador, com ícone opcional.
Timeline.Connector: a linha até o próximo evento (some no último).
Timeline.Content: o conteúdo do evento.

Propriedades

Raiz (Timeline):

Timeline
Prop	Tipo	Padrão	Descrição
`children`*	`React.ReactNode`	-	Conteúdo do componente.
`axis`	`'center' \| 'start'`	`"start"`	Posição do eixo: `start` (na borda) ou `center`.
`className`	`string`	-	Classes CSS aplicadas ao elemento.
`density`	`'compact' \| 'comfortable'`	`"comfortable"`	Ritmo vertical entre os eventos: `compact` ou `comfortable`.
`itemAlign`	`'center' \| 'start'`	`"start"`	Alinhamento vertical padrão do conteúdo dos itens: `start` ou `center`.
`placement`	`TimelinePlacement`	`"end"`	Lado do conteúdo em relação ao eixo: `start` ou `end` (padrão).
`size`	`'lg' \| 'md' \| 'sm'`	`"md"`	Tamanho dos marcadores e do texto: `sm`, `md` (padrão) ou `lg`.
`style`	`React.CSSProperties`	-	Estilos em linha aplicados ao elemento.

Item (Timeline.Item):

Timeline.Item
Prop	Tipo	Padrão	Descrição
`_index`	`number`	-	Uso interno do componente: não defina.
`_isLast`	`boolean`	-	Uso interno do componente: não defina.
`_side`	`TimelineSide`	-	Uso interno do componente: não defina.
`align`	`TimelineItemAlign`	`inherited`	Alinhamento vertical do conteúdo deste item.
`children`	`React.ReactNode`	-	Conteúdo do componente.
`className`	`string`	-	Classes CSS aplicadas ao elemento.
`side`	`TimelineSide`	-	Lado do conteúdo quando o eixo é central: `start` ou `end`.
`status`	`TimelineStatus`	`"default"`	Tom do marcador, que indica o estado do evento.
`style`	`React.CSSProperties`	-	Estilos em linha aplicados ao elemento.

Animações

Sem movimento
indicativo

A Timeline não anima. Para destacar o evento mais novo, componha com a camada de movimento da fachada (@rastreio-x/ui/motion) respeitando prefers-reduced-motion.

Acessibilidade

Renderiza uma lista ordenada (ol) com itens li; passe aria-label ("Jornada do Pedido ped-8").
Conectores e marcadores vazios são decorativos e ficam fora da árvore de acessibilidade.
status="current" marca o item com aria-current; no Admin usamos aria-current="step" na Jornada.
Use <time dateTime> para datas, e diga o estado no texto ("— atrasado").

Boas práticas

Faça

Marcador com ícone e o estado dito em texto: Saiu para Entrega, atrasado.

Evite

Marcador que só muda de cor, ou Stepper interativo para uma cronologia de leitura.

Ordem cronológica estável, do mais antigo ao mais novo (ou o inverso, sempre igual).
Horário previsto e horário real devem ser distinguíveis (rótulo "previsto").
Evite chip redundante por item; um sinal por estado.
Para histórico longo, pagine ou recolha.

Relacionados

Chip para o estado de um item.
Card para agrupar a Jornada com outros blocos.
Widget como contêiner nas telas de detalhe.