Timeline

Linha do tempo cronológica composta por `mk-timeline` e `mk-timeline-item`, com status, alinhamento e conteúdo oposto.

A mk-timeline apresenta uma sequência de eventos em ordem cronológica — histórico de um pedido, etapas de um fluxo, registro de atividades. O contêiner mk-timeline controla o alinhamento; cada mk-timeline-item exibe um marcador, um título, um texto secundário e, opcionalmente, conteúdo no lado oposto do conector (data/hora).

Padrão

No modo padrão (align="end"), os itens são empilhados de cima para baixo com o conteúdo após o marcador.

import { MkTimeline, MkTimelineItem } from '@db1/makuco-ui-react';

<MkTimeline>
  <MkTimelineItem status="completed" label="Pedido criado" description="Há 3 dias" />
  <MkTimelineItem status="active" label="Em transporte" description="Saiu para entrega" />
  <MkTimelineItem status="pending" label="Entregue" description="Previsão: amanhã" />
</MkTimeline>

<mk-timeline>
  <mk-timeline-item status="completed" label="Pedido criado" description="Há 3 dias"></mk-timeline-item>
  <mk-timeline-item status="active" label="Em transporte" description="Saiu para entrega"></mk-timeline-item>
  <mk-timeline-item status="pending" label="Entregue" description="Previsão: amanhã"></mk-timeline-item>
</mk-timeline>

Status

Quatro status definem a cor do marcador e do conector: completed (concluído), active (em andamento — halo destacando a etapa atual), pending (pendente — dot vazado) e error (falha — halo vermelho).

A ordem dos status segue a progressão lógica do fluxo: um item pending nunca deve vir antes de um error (pois o erro encerra o progresso), e um error não deve ser seguido de active (uma etapa não pode estar em andamento após uma falha).

Fluxo normal — completed → active → pending

<MkTimeline>
  <MkTimelineItem status="completed" label="Pedido criado" description="Pagamento aprovado" />
  <MkTimelineItem status="active" label="Em transporte" description="Saiu para entrega" />
  <MkTimelineItem status="pending" label="Entregue" description="Aguardando" />
</MkTimeline>

<mk-timeline>
  <mk-timeline-item status="completed" label="Pedido criado" description="Pagamento aprovado"></mk-timeline-item>
  <mk-timeline-item status="active" label="Em transporte" description="Saiu para entrega"></mk-timeline-item>
  <mk-timeline-item status="pending" label="Entregue" description="Aguardando"></mk-timeline-item>
</mk-timeline>

Fluxo com erro — completed → error

Quando uma etapa falha, as subsequentes não acontecem. Use error na etapa que falhou e deixe as restantes como pending.

<MkTimeline>
  <MkTimelineItem status="completed" label="Pedido criado" description="Pagamento aprovado" />
  <MkTimelineItem status="error" label="Falha na entrega" description="Endereço não localizado" />
  <MkTimelineItem status="pending" label="Reagendamento" description="Aguardando" />
</MkTimeline>

<mk-timeline>
  <mk-timeline-item status="completed" label="Pedido criado" description="Pagamento aprovado"></mk-timeline-item>
  <mk-timeline-item status="error" label="Falha na entrega" description="Endereço não localizado"></mk-timeline-item>
  <mk-timeline-item status="pending" label="Reagendamento" description="Aguardando"></mk-timeline-item>
</mk-timeline>

Alinhamento

align controla o lado do conteúdo em relação ao conector: end (padrão, após o marcador), start (antes do marcador) e alternate (alterna a cada item). No modo alternate, o slot opposite aparece no lado oposto ao conteúdo.

<MkTimeline align="alternate">
  <MkTimelineItem status="completed" label="Reunião inicial">
    <span slot="opposite">09:00</span>
  </MkTimelineItem>
  <MkTimelineItem status="active" label="Prototipação">
    <span slot="opposite">14:00</span>
  </MkTimelineItem>
</MkTimeline>

<mk-timeline align="alternate">
  <mk-timeline-item status="completed" label="Reunião inicial">
    <span slot="opposite">09:00</span>
  </mk-timeline-item>
  <mk-timeline-item status="active" label="Prototipação">
    <span slot="opposite">14:00</span>
  </mk-timeline-item>
</mk-timeline>

Props — mk-timeline

Prop	Tipo	Padrão	Descrição
`align`	`"start" \| "end" \| "alternate"`	`"end"`	Alinhamento do conteúdo em relação ao conector.
`ariaLabel`	`string`	`"Linha do tempo"`	Rótulo acessível anunciado por leitores de tela. Deve descrever o contexto quando há mais de uma timeline na página.

Props — mk-timeline-item

Prop	Tipo	Padrão	Descrição
`label`	`string`	—	Título do item. Ignorado quando o slot `content` é fornecido.
`description`	`string`	—	Texto secundário do item. Ignorado quando o slot `content` é fornecido.
`status`	`"completed" \| "active" \| "pending" \| "error"`	`"pending"`	Status do item — define a cor do marcador e do conector.

Eventos

Os componentes não emitem eventos customizados.

Slots

Componente	Slot	Descrição
`mk-timeline`	(default)	Deve conter instâncias de `mk-timeline-item`.
`mk-timeline-item`	`content`	Substitui `label` + `description` para composição avançada.
`mk-timeline-item`	`opposite`	Conteúdo no lado oposto do conector (ex.: timestamp). Exibido apenas com `align="alternate"`.

Acessibilidade

mk-timeline é renderizado como <ol> (lista ordenada), refletindo a sequência cronológica.
Cada mk-timeline-item é renderizado como <li> (recebe role="listitem" quando filho direto de mk-timeline).
O marcador é decorativo e recebe aria-hidden="true" — o significado deve vir do label/description ou do slot content.
O status não é transmitido apenas por cor: a forma do dot (preenchido, vazado ou com halo) reforça a distinção, e o significado textual deve estar no label/description. O contraste atende ao WCAG 2.1 AA.

Timeline

On this page