타임라인 다이어그램

타임라인이란

**타임라인 다이어그램(timeline diagram)**은 시간 축을 따라 이벤트를 배열하여 연대기적 관계를 즉시 파악할 수 있도록 합니다. 프로젝트 관리자는 스프린트 일정과 마일스톤을 표시하는 데 사용하고, 역사가는 발견들을 맥락 안에 배치하며, 저널리스트는 사건 순서를 재구성하고, 임상 연구자는 치료 과정을 매핑합니다. 이 시각적 형식을 지배하는 단일 표준은 없지만, 표기 방식은 보편적입니다. 시간은 왼쪽에서 오른쪽으로 흐르고, 이벤트는 날짜에 표시되며, 기간은 스팬으로 표현됩니다.

Schematex는 세 가지 시각적 스타일로 타임라인을 렌더링합니다. swimlane (이벤트가 축 위아래로 펼쳐짐), gantt (수평 기간 바, 프로젝트 일정에 유용), lollipop (막대 위 점 마커, 역사적 회고에 유용). 세 가지 모두 동일한 DSL을 공유하며, style 설정 키로 전환합니다.

1. 첫 번째 타임라인

가장 작은 유용한 타임라인: 제목, 두 개의 일반 이벤트, 하나의 마일스톤.

사용법의 80%를 커버하는 네 가지 규칙:

1. timeline 키워드로 시작하고, 선택적으로 따옴표로 묶인 제목을 사용합니다.
2. 각 이벤트는 DATE: "Label" 형식입니다. 날짜, 콜론, 따옴표로 묶인 레이블. milestone 키워드를 레이블 앞에 넣으면 해당 이벤트가 마일스톤으로 표시됩니다.
3. 날짜 범위는 DATE - DATE: 또는 DATE .. DATE: 형식입니다(둘 다 동등합니다).
4. 따옴표 레이블 뒤에 [key: value] 속성을 추가하여 색상, 배치 면, 모양, 카테고리를 설정합니다.

주석은 해당 줄의 맨 앞에 # 또는 //로 시작해야 합니다.

2. 이벤트

이벤트 줄은 특정 시점(또는 기간에 걸친 바)에 레이블이 있는 마커를 배치합니다.

2.1 시점 이벤트

2024-09-15: "Conference keynote"

2.2 범위 이벤트

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

두 구분자(- 공백 포함, 또는 ..)는 동등합니다.

2.3 마일스톤

2024-09-01: milestone "Public launch"

따옴표 레이블 앞의 milestone 키워드는 마커를 다이아몬드 모양으로 전환합니다.

2.4 이벤트 속성

속성은 따옴표 레이블 뒤, 줄 바꿈 전에 [key: value, …] 형식으로 작성합니다.

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

3. 날짜 형식

모든 날짜 형식은 이벤트, 에라(era), 범위에서 날짜가 필요한 곳 어디에서든 사용할 수 있습니다.

4. 에라 (배경 기간)

era 줄은 시간 축 위에 음영 처리된 배경 밴드를 그립니다. 항상 날짜 범위가 필요합니다.

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

[color: …] 속성은 선택 사항입니다. 겹치는 에라는 자동으로 별도의 밴드로 쌓입니다.

5. 트랙 (swimlane 그룹)

track 블록은 관련 이벤트를 명명된 swimlane으로 그룹화합니다. 들여쓰기된 이벤트 줄(2칸)이 트랙에 속합니다.

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]

트랙은 gantt 스타일에서 가장 유용합니다. 각 트랙이 레이블이 있는 고유한 행이 됩니다.

6. 노트

이벤트 아래에 들여쓰기된 note: 줄은 해당 이벤트에 툴팁 주석을 부착합니다.

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

노트는 평면 이벤트와 트랙 내부 이벤트 모두에서 작동합니다.

7. 설정

config: 줄로 레이아웃과 시각적 스타일을 조정합니다. 각 항목은 config: key = value 형식의 독립된 줄입니다.

스타일 참고:

• swimlane — 이벤트가 수평 축 위아래로 교대로 배치됩니다. side:로 이벤트별 배치를 제어합니다. 에라는 색상 배경 밴드를 추가합니다. 로드맵과 전기(biography)에 적합합니다.
• gantt — 각 명명된 트랙이 수평 바 레인이 됩니다. 마일스톤은 바 위의 핀이 됩니다. gantt-project는 별칭입니다. 프로젝트 일정에 적합합니다.
• lollipop — 중앙 축과 교대 줄기 위의 레이블 카드. 희소하고 기억할 만한 이벤트가 있는 역사적 회고에 적합합니다.

Swimlane — 로드맵, 제품 타임라인, 전기. 에라가 색상 밴드를 추가하며 이벤트가 위아래로 교대합니다.

Gantt — 수평 기간 바와 마일스톤 핀이 있는 병렬 트랙. 프로젝트 일정에 적합합니다.

Lollipop — 중앙 축과 교대 카드가 있는 희소한 마일스톤. 역사적 회고와 브랜드 스토리에 적합합니다.

8. 레이블 및 주석

• 제목: timeline "My Title" — 첫 번째 줄에만.
• 이벤트 레이블: 콜론 뒤의 따옴표 문자열: DATE: "Label".
• 마일스톤 레이블: DATE: milestone "Label".
• 에라 레이블: era DATE - DATE: "Label".
• 트랙 이름: track "Name":.
• 노트: 이벤트 아래에 들여쓰기된 note: "text".
• 주석: 줄의 앞부분(선행 공백 이후) # 또는 //.

9. 예약어 및 이스케이프

줄 시작 예약어: timeline (헤더), config:, era, track, note:.

날짜 범위 구분자: - (공백-하이픈-공백)와 .. — 콜론 앞에 나오는 레이블 텍스트 내에서는 이 시퀀스를 피하십시오.

음수 정수 BC 연도: -753은 기원전 753년입니다. 파서는 주변 공백을 확인하여 음수 부호와 범위 구분자를 구별합니다. - (공백 포함)는 범위이고, -753 (콜론 뒤 선행 공백 없음)은 BC 연도입니다.

속성 블록: [key: value]는 같은 줄의 따옴표 레이블 뒤에 나와야 합니다. 닫히는 ]가 반드시 있어야 하며, 닫히지 않은 괄호는 파싱 오류를 발생시킵니다.

10. 흔한 실수

11. 문법 (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

공식 소스: src/diagrams/timeline/parser.ts. 이 내용이 파서와 다를 경우 파서가 기준입니다. 이슈를 열어 주십시오.

12. 표준 준수

타임라인 다이어그램에는 단일 지배 표준이 없습니다. Schematex는 확립된 시각화 표기 방식을 따릅니다.

• Swimlane 스타일 — 학문적 역사학과 프로젝트 관리(PMI PMBOK)에서 사용되는 수평 타임라인 표기 방식에서 채택.
• Gantt 스타일 — Henry Gantt(1910–1915)가 도입한 간트 차트 형식을 따름; 트랙별 바 레이아웃은 ISO 21500 프로젝트 일정 표기 방식과 일치.
• Lollipop 스타일 — 데이터 저널리즘과 인포그래픽에서 일반적인 점 도표 / 줄기 도표 표기 방식을 따름.

현재 구현된 사항:

• ✅ 세 가지 시각적 스타일: swimlane, gantt, lollipop
• ✅ 수평 및 수직 방향
• ✅ 세 가지 스케일 모드: proportional, equidistant, log
• ✅ 시점 이벤트, 범위 이벤트(바), 마일스톤 마커
• ✅ 에라 (배경 음영 밴드)
• ✅ 명명된 트랙 (swimlane 행)
• ✅ 이벤트 노트
• ✅ 여섯 가지 날짜 형식: 전체 날짜, 연-월, 연도, 분기, BC 연도, 지질학적 (Ma/Ga/ka)
• ✅ 이벤트 속성: color, side, icon, shape, category
• ⏳ 수직 방향 렌더링 (파싱됨, 레이아웃 미구현)
• ⏳ log 스케일 렌더링 (파싱됨, 현재 레이아웃은 proportional로 처리)
• ⏳ 사용자 정의 형식 문자열이 있는 축 눈금 레이블
• ⏳ 이벤트 연결자 (관련 이벤트 간 화살표)

참고 문헌:

• Gantt, H.L. (1910). Work, Wages, and Profits. Engineering Magazine.
• Tufte, E.R. (1983). The Visual Display of Quantitative Information. — 소규모 배수로서의 타임라인.

13. 로드맵

계획 중 — 아직 파싱 불가. 오늘 생성된 DSL에서는 사용하지 마십시오. 파서가 거부하거나 무시합니다.

• 이벤트 연결자 — connect ev1 -> ev2 [label: "causes"] 형식으로 시간을 가로질러 두 이벤트를 연결하는 화살표.
• 반복/재발 — every 2024-Q1 .. 2024-Q4 monthly: "Sprint review" 형식으로 정기 이벤트 표현.
• 축 눈금 형식 — config: tickFormat = "%b %Y" 형식으로 축의 날짜 표시 사용자 정의.
• 수직 방향 — config: orientation = vertical 형식으로 수직 축 좌우에 이벤트 배치 (파싱됨; 렌더링 지연).
• Log 스케일 — config: scale = log 형식으로 압축된 최근 연도가 필요한 지질학적 또는 심층 역사 기간용 (파싱됨; 레이아웃 지연).

더 빠른 구현이 필요하시면 GitHub 이슈에서 추적하십시오.

관련 예제

예제 갤러리의 바로 사용 가능한 시나리오: