Timeline diagram

Sobre diagramas de linha do tempo

Um diagrama de linha do tempo organiza eventos ao longo de um eixo de tempo compartilhado, tornando as relações cronológicas imediatamente visíveis. Gerentes de projeto os usam para mostrar cronogramas de sprints e marcos; historiadores os usam para contextualizar descobertas; jornalistas os usam para reconstruir sequências de eventos; pesquisadores clínicos os usam para mapear cursos de tratamento. A forma visual não tem um padrão único, mas as convenções são universais: o tempo corre da esquerda para a direita, os eventos são marcados em suas datas e os intervalos mostram a duração.

O Schematex renderiza linhas do tempo em três estilos visuais — swimlane (eventos alternados acima e abaixo de um eixo), gantt (barras horizontais de duração, úteis para agendamento de projetos) e lollipop (marcadores em haste com ponto, úteis para retrospectivas históricas). Os três compartilham a mesma DSL; a chave de configuração style alterna entre eles.

1. Sua primeira linha do tempo

A menor linha do tempo útil: um título, dois eventos comuns e um marco.

Quatro regras cobrem 80% dos casos de uso:

1. Comece com a palavra-chave timeline, opcionalmente seguida de um título entre aspas.
2. Cada evento é DATE: "Label" — uma data, dois pontos e um rótulo entre aspas. A palavra-chave milestone antes do rótulo marca o evento como um marco.
3. Intervalos de datas usam DATE - DATE: ou DATE .. DATE: (ambos são equivalentes).
4. Adicione propriedades [key: value] após o rótulo entre aspas para definir cor, posicionamento, forma ou categoria.

Comentários devem começar com # ou // na própria linha.

2. Eventos

Uma linha de evento coloca um marcador rotulado em um ponto no tempo (ou uma barra ao longo de um intervalo).

2.1 Eventos pontuais

2024-09-15: "Conference keynote"

2.2 Eventos com intervalo

2024-06-01 - 2024-08-31: "Q3 development sprint"
2024-06-01 .. 2024-08-31: "Q3 development sprint"

Ambos os separadores (- cercado de espaços, ou ..) são equivalentes.

2.3 Marcos

2024-09-01: milestone "Public launch"

A palavra-chave milestone antes do rótulo entre aspas muda o marcador para uma forma de losango.

2.4 Propriedades de evento

As propriedades ficam em [key: value, …] após o rótulo entre aspas, antes da quebra de linha.

2024-09-01: milestone "Launch day" [color: #E53935, side: above]
2024-07-15: "Beta ships" [icon: 🚀, category: "product"]

3. Formatos de data

Todos os formatos de data podem aparecer em qualquer lugar onde uma data é esperada — em eventos, eras e intervalos.

4. Eras (intervalos de fundo)

Uma linha era desenha uma faixa de fundo sombreada ao longo do eixo de tempo. Ela sempre requer um intervalo de datas.

era 2020 - 2022: "Foundation Phase"
era 2022 .. 2025: "Growth Phase" [color: #E8F5E9]

A propriedade [color: …] é opcional. Eras sobrepostas se empilham em faixas separadas automaticamente.

5. Faixas (agrupamento em swimlane)

Um bloco track agrupa eventos relacionados em uma swimlane nomeada. As linhas de evento indentadas (2 espaços) pertencem à faixa.

track "Engineering":
  2024-01-15 - 2024-03-31: "API design"
  2024-04-01 - 2024-07-31: "Implementation"

track "Marketing":
  2024-06-01: "Campaign kick-off"
  2024-09-01: milestone "Launch campaign" [color: #1B5E20]

As faixas são mais úteis no estilo gantt, onde cada faixa se torna sua própria linha rotulada.

6. Notas

Uma linha note: indentada sob um evento anexa uma anotação de dica a ele.

2024-06-01: "Beta launch"
  note: "First external users; NPS target 40+"

As notas funcionam tanto para eventos simples quanto para eventos dentro de faixas.

7. Configuração

Linhas config: ajustam o layout e o estilo visual. Cada uma é sua própria linha no formato config: key = value.

Notas sobre estilos:

• swimlane — eventos alternam acima e abaixo de um eixo horizontal; side: controla o posicionamento por evento. Eras adicionam faixas de fundo coloridas. Melhor para roadmaps e biografias.
• gantt — cada faixa nomeada se torna uma lane de barra horizontal; marcos se tornam pinos acima das barras. gantt-project é um alias. Melhor para agendamento de projetos.
• lollipop — um eixo central com cartões rotulados em hastes alternadas. Melhor para retrospectivas históricas com eventos esparsos e memoráveis.

Swimlane — roadmaps, linhas do tempo de produto, biografias. Eras adicionam faixas de cor; eventos alternam acima e abaixo.

Gantt — faixas paralelas com barras de duração horizontais e pinos de marco. Melhor para agendamento de projetos.

Lollipop — marcos esparsos em um eixo central com cartões alternados. Melhor para retrospectivas históricas e histórias de marca.

8. Rótulos e comentários

• Título: timeline "My Title" — apenas na primeira linha.
• Rótulo do evento: string entre aspas após os dois pontos: DATE: "Label".
• Rótulo do marco: DATE: milestone "Label".
• Rótulo de era: era DATE - DATE: "Label".
• Nome da faixa: track "Name":.
• Nota: note: "text" indentado sob um evento.
• Comentários: # ou // no início de uma linha (após espaços em branco iniciais).

9. Palavras reservadas e escapamento

Reservadas no início da linha: timeline (cabeçalho), config:, era, track, note:.

Separadores de intervalo de data: - (espaço-hífen-espaço) e .. — evite essas sequências dentro do texto do rótulo que aparece antes dos dois pontos.

Anos a.C. como inteiros negativos: -753 é o ano 753 a.C. O parser distingue o sinal negativo de um separador de intervalo verificando os espaços ao redor — - (com espaços) é um intervalo; -753 (sem espaço antes após dois pontos) é um ano a.C.

Blocos de propriedade: [key: value] deve aparecer após o rótulo entre aspas na mesma linha. O ] de fechamento deve estar presente; colchetes não fechados produzem erro de parse.

10. Erros comuns

11. Gramática (EBNF)

document     = header ( blank | comment | config | era | track | event )*

header       = "timeline" ( WS quoted-string )? NEWLINE
quoted-string = '"' any-char-but-quote* '"'

config       = "config:" WS key WS "=" WS value NEWLINE
key          = "style" | "orientation" | "scale" | "axis"

era          = "era" WS date-range ":" WS quoted-string ( WS props )? NEWLINE
track        = "track" WS quoted-string ":" NEWLINE
                 ( INDENT≥2 event | INDENT≥2 note )*

event        = date-spec ":" WS event-body ( WS props )? NEWLINE
               ( INDENT note )?
event-body   = ( "milestone" WS )? quoted-string
date-spec    = date ( ( " - " | ".." ) date )?

note         = "note:" WS quoted-string NEWLINE

props        = "[" prop-list "]"
prop-list    = prop ( "," prop )*
prop         = key ":" WS value
             | key ":" WS quoted-string

date         = iso-date | year-month | year | quarter | bc-year | geological
iso-date     = digit{4} "-" digit{2} "-" digit{2}
year-month   = digit{4} "-" digit{2}
year         = "-"? digit{1,5}
quarter      = digit{4} "-"? "Q" [1-4]
bc-year      = digit+ ( "BC" | "BCE" )
geological   = number ( "Ma" | "Ga" | "ka" )

comment      = ( "#" | "//" ) any NEWLINE

Fonte autoritativa: src/diagrams/timeline/parser.ts. Se houver divergência com o parser, o parser prevalece — por favor, abra uma issue.

12. Conformidade com padrões

Os diagramas de linha do tempo não têm um padrão único. O Schematex segue convenções de visualização estabelecidas:

• Estilo swimlane — adaptado da convenção de linha do tempo horizontal usada em historiografia acadêmica e gestão de projetos (PMI PMBOK).
• Estilo gantt — segue a forma do gráfico de Gantt introduzida por Henry Gantt (1910–1915); o layout de barra por faixa corresponde à convenção de agendamento de projetos ISO 21500.
• Estilo lollipop — segue a convenção de gráfico de pontos / gráfico de haste comum no jornalismo de dados e infográficos.

O que está implementado atualmente:

• ✅ Três estilos visuais: swimlane, gantt, lollipop
• ✅ Orientação horizontal e vertical
• ✅ Três modos de escala: proportional, equidistant, log
• ✅ Eventos pontuais, eventos com intervalo (barras) e marcos
• ✅ Eras (faixas de sombreamento de fundo)
• ✅ Faixas nomeadas (linhas de swimlane)
• ✅ Notas de evento
• ✅ Seis formatos de data: data completa, ano-mês, ano, trimestre, ano a.C., geológico (Ma/Ga/ka)
• ✅ Propriedades de evento: color, side, icon, shape, category
• ⏳ Renderização de orientação vertical (parseada, layout ainda não implementado)
• ⏳ Renderização de escala log (parseada, layout trata como proporcional hoje)
• ⏳ Rótulos de marcação de eixo com strings de formato personalizadas
• ⏳ Conectores de evento (setas entre eventos relacionados)

Referências:

• Gantt, H.L. (1910). Work, Wages, and Profits. Engineering Magazine.
• Tufte, E.R. (1983). The Visual Display of Quantitative Information. — Timeline como pequenos múltiplos.

13. Roadmap

Planejado — ainda não parseável. Não use estes itens em DSL gerado hoje; o parser os rejeitará ou ignorará.

• Conectores de evento — setas connect ev1 -> ev2 [label: "causes"] vinculando dois eventos ao longo do tempo.
• Repetição / recorrência — every 2024-Q1 .. 2024-Q4 monthly: "Sprint review" para eventos regulares.
• Formato de marcação de eixo — config: tickFormat = "%b %Y" para exibição personalizada de datas no eixo.
• Orientação vertical — config: orientation = vertical com eventos à esquerda/direita de um eixo vertical (parseado; renderização adiada).
• Escala logarítmica — config: scale = log para intervalos geológicos ou de história profunda que precisam de anos recentes comprimidos (parseado; layout adiado).

Acompanhe nas issues do GitHub se precisar de algum desses itens mais cedo.

Exemplos relacionados

Cenários prontos para uso da galeria de exemplos: