Diagrama de línea de tiempo

Sobre las líneas de tiempo

Un diagrama de línea de tiempo organiza eventos a lo largo de un eje de tiempo compartido para que las relaciones cronológicas sean inmediatamente visibles. Los gestores de proyectos los usan para mostrar calendarios de sprints e hitos; los historiadores los usan para situar descubrimientos en contexto; los periodistas los usan para reconstruir secuencias de eventos; los investigadores clínicos los usan para mapear cursos de tratamiento. La forma visual no tiene un estándar rector único, pero las convenciones son universales: el tiempo corre de izquierda a derecha, los eventos se marcan en sus fechas y los rangos muestran la duración.

Schematex renderiza líneas de tiempo en tres estilos visuales — swimlane (eventos distribuidos arriba y abajo de un eje), gantt (barras de duración horizontales, útiles para planificación de proyectos) y lollipop (marcadores de punto en palito, útiles para retrospectivas históricas). Los tres comparten el mismo DSL; la clave de config style cambia entre ellos.

1. Tu primera línea de tiempo

La línea de tiempo mínima útil: un título, dos eventos ordinarios y un hito.

Cuatro reglas cubren el 80 % del uso:

1. Comienza con la palabra clave timeline, seguida opcionalmente de un título entre comillas.
2. Cada evento es FECHA: "Etiqueta" — una fecha, dos puntos, luego una etiqueta entre comillas. La palabra clave milestone antes de la etiqueta marca el evento como hito.
3. Los rangos de fecha usan FECHA - FECHA: o FECHA .. FECHA: (ambos son equivalentes).
4. Agrega propiedades [clave: valor] después de la etiqueta entre comillas para establecer color, posición lateral, forma o categoría.

Los comentarios deben comenzar con # o // en su propia línea.

2. Eventos

Una línea de evento coloca un marcador etiquetado en un punto en el tiempo (o una barra en un rango).

2.1 Eventos puntuales

2024-09-15: "Conference keynote"

2.2 Eventos de rango

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

Ambos separadores (- rodeado de espacios, o ..) son equivalentes.

2.3 Hitos

2024-09-01: milestone "Public launch"

La palabra clave milestone antes de la etiqueta entre comillas cambia el marcador a forma de rombo.

2.4 Propiedades de evento

Las propiedades van en [clave: valor, …] después de la etiqueta entre comillas, antes del salto de línea.

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

3. Formatos de fecha

Todos los formatos de fecha pueden aparecer donde se espere una fecha — en eventos, eras y rangos.

4. Eras (franjas de fondo)

Una línea era dibuja una banda de fondo sombreada a lo largo del eje de tiempo. Siempre requiere un rango de fechas.

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

La propiedad [color: …] es opcional. Las eras que se solapan se apilan en bandas separadas automáticamente.

5. Carriles (agrupación swimlane)

Un bloque track agrupa eventos relacionados en un carril con nombre. Las líneas de evento indentadas (2 espacios) pertenecen al carril.

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]

Los carriles son más útiles en el estilo gantt, donde cada carril se convierte en su propio carril de barra etiquetado.

6. Notas

Una línea note: indentada bajo un evento adjunta una anotación de tooltip.

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

Las notas funcionan tanto para eventos planos como para eventos dentro de carriles.

7. Configuración

Las líneas config: ajustan el diseño y el estilo visual. Cada una es su propia línea con la forma config: clave = valor.

Notas de estilo:

• swimlane — los eventos se alternan arriba y abajo de un eje horizontal; side: controla el posicionamiento por evento. Las eras añaden bandas de fondo coloreadas. Ideal para hojas de ruta y biografías.
• gantt — cada carril nombrado se convierte en un carril de barra horizontal; los hitos se convierten en pines sobre las barras. gantt-project es un alias. Ideal para planificación de proyectos.
• lollipop — un eje central con tarjetas etiquetadas en palitos alternos. Ideal para retrospectivas históricas con eventos dispersos y memorables.

Swimlane — hojas de ruta, líneas de tiempo de productos, biografías. Las eras añaden bandas de color; los eventos se alternan arriba y abajo.

Gantt — carriles paralelos con barras de duración horizontales y pines de hito. Ideal para planificación de proyectos.

Lollipop — hitos dispersos en un eje central con tarjetas alternas. Ideal para retrospectivas históricas y relatos de marca.

8. Etiquetas y comentarios

• Título: timeline "Mi título" — solo en la primera línea.
• Etiqueta de evento: cadena entre comillas después de los dos puntos: FECHA: "Etiqueta".
• Etiqueta de hito: FECHA: milestone "Etiqueta".
• Etiqueta de era: era FECHA - FECHA: "Etiqueta".
• Nombre de carril: track "Nombre":.
• Nota: note: "texto" indentado bajo un evento.
• Comentarios: # o // al inicio de una línea (después del espacio en blanco inicial).

9. Palabras reservadas y escapado

Reservadas al inicio de línea: timeline (encabezado), config:, era, track, note:.

Separadores de rango de fechas: - (espacio-guion-espacio) y .. — evita estas secuencias dentro del texto de etiqueta que aparece antes de los dos puntos.

Años a. C. como enteros negativos: -753 es el año 753 a. C. El parser distingue el signo negativo de un separador de rango verificando el espacio en blanco circundante — - (con espacios) es un rango; -753 (sin espacio inicial después de dos puntos) es un año a. C.

Bloques de propiedades: [clave: valor] debe aparecer después de la etiqueta entre comillas en la misma línea. El ] de cierre debe estar presente; los corchetes sin cerrar producen un error de análisis.

10. Errores comunes

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

Fuente autoritativa: src/diagrams/timeline/parser.ts. Si esto diverge del parser, el parser tiene prioridad — por favor abre un issue.

12. Conformidad con el estándar

Los diagramas de línea de tiempo no tienen un estándar rector único. Schematex sigue convenciones de visualización establecidas:

• Estilo swimlane — adaptado de la convención de línea de tiempo horizontal usada en historiografía académica y gestión de proyectos (PMI PMBOK).
• Estilo gantt — sigue la forma de diagrama de Gantt introducida por Henry Gantt (1910–1915); el diseño de barra por carril coincide con la convención de programación de proyectos ISO 21500.
• Estilo lollipop — sigue la convención de diagrama de puntos / gráfico de tallos común en periodismo de datos e infografías.

Lo que está implementado actualmente:

• ✅ Tres estilos visuales: swimlane, gantt, lollipop
• ✅ Orientación horizontal y vertical
• ✅ Tres modos de escala: proporcional, equidistante, log
• ✅ Eventos puntuales, eventos de rango (barras) y marcadores de hito
• ✅ Eras (bandas de sombreado de fondo)
• ✅ Carriles con nombre (filas de swimlane)
• ✅ Notas de evento
• ✅ Seis formatos de fecha: fecha completa, año-mes, año, trimestre, año a. C., geológico (Ma/Ga/ka)
• ✅ Propiedades de evento: color, side, icon, shape, category
• ⏳ Renderizado de orientación vertical (analizado, diseño aún no implementado)
• ⏳ Renderizado de escala log (analizado, el diseño trata como proporcional hoy)
• ⏳ Etiquetas de marcas del eje con cadenas de formato personalizadas
• ⏳ Conectores de eventos (flechas entre eventos relacionados)

Referencias:

• Gantt, H.L. (1910). Work, Wages, and Profits. Engineering Magazine.
• Tufte, E.R. (1983). The Visual Display of Quantitative Information. — La línea de tiempo como pequeños múltiplos.

13. Hoja de ruta

Planificado — aún no analizable. No uses esto en el DSL generado hoy; el parser lo rechazará o ignorará.

• Conectores de eventos — flechas connect ev1 -> ev2 [label: "causes"] que vinculan dos eventos a través del tiempo.
• Repetición / recurrencia — every 2024-Q1 .. 2024-Q4 monthly: "Sprint review" para eventos regulares.
• Formato de marcas del eje — config: tickFormat = "%b %Y" para visualización de fecha personalizada en el eje.
• Orientación vertical — config: orientation = vertical con eventos a la izquierda/derecha de un eje vertical (analizado; renderizado diferido).
• Escala log — config: scale = log para rangos geológicos o de historia profunda que necesitan años recientes comprimidos (analizado; diseño diferido).

Síguelo en los issues de GitHub si necesitas alguno de estos antes.

Ejemplos relacionados

Escenarios listos para usar del catálogo de ejemplos: