src/primitives/timeline.ts

Functions

Imports

It imports src/html.ts, src/primitives/companion.ts, src/render/data.ts, src/render/size.ts. Imported by src/index.ts.

Source

1import { element, escapeHtml } from "../html.js";
2import {
3  DAY,
4  defaultFormat,
5  formatInstant,
6  maxOf,
7  minOf,
8  requireSize,
9  toDate,
10} from "../render/data.js";
11import { DEFAULT_WIDTH } from "../render/size.js";
12import { type PrimitiveTable, type PrimitiveTableOptions, primitiveTable } from "./companion.js";
13
14/** What happened, as the theme's status colors and a shape say it. */
15export type TimelineStatus = "ok" | "warning" | "error" | "unknown";
16
17/** A time: a Date, an ISO 8601 string, or epoch milliseconds. Instants, in UTC. */
18export type TimelineTime = Date | string | number;
19
20/** An event that happened at one moment. */
21export interface TimelinePoint {
22  /** The lane it belongs to: a site, an agent, a service. */
23  readonly lane: string;
24  /** What happened, e.g. "Deploy 41". Hover details, the plain list and the table carry it. */
25  readonly label: string;
26  readonly status: TimelineStatus;
27  readonly at: TimelineTime;
28  readonly from?: never;
29  readonly to?: never;
30}
31
32/** An event that lasted from one moment to another. */
33export interface TimelineSpan {
34  readonly lane: string;
35  readonly label: string;
36  readonly status: TimelineStatus;
37  readonly from: TimelineTime;
38  readonly to: TimelineTime;
39  readonly at?: never;
40}
41
42/** One event on a {@link timeline}: a point or a span. */
43export type TimelineEvent = TimelinePoint | TimelineSpan;
44
45/** Options for {@link timeline}. */
46export interface TimelineOptions {
47  /** The events, in any order. */
48  readonly events: readonly TimelineEvent[];
49  /**
50   * The lanes, top to bottom. Every event's lane must be among them. Without it, lanes are in
51   * first-seen order. A lane with no events is drawn empty.
52   */
53  readonly lanes?: readonly string[];
54  /** The start of the time window (default: the earliest event). */
55  readonly start?: TimelineTime;
56  /** The end of the time window (default: the latest event). */
57  readonly end?: TimelineTime;
58  /**
59   * What the timeline shows, e.g. "Agent runs, 9 to 12 June"; it starts the generated text
60   * alternative. Required unless `alt` is given.
61   */
62  readonly label?: string;
63  /** The text alternative, instead of the one generated from `label` and the events. */
64  readonly alt?: string;
65  /** The drawing's width in CSS pixels (default 640). Under 30rem of room it gives way to a list. */
66  readonly width?: number;
67  /** Formats an instant in hover details and the plain list (default `2026-01-05 14:30 UTC`). */
68  readonly formatTime?: (time: Date) => string;
69}
70
71const KIND = "timeline";
72const STATUSES: Readonly<Record<TimelineStatus, { color: string; word: string }>> = {
73  ok: { color: "var(--enarratio-status-good)", word: "ok" },
74  warning: { color: "var(--enarratio-status-warning)", word: "warning" },
75  error: { color: "var(--enarratio-status-bad)", word: "error" },
76  unknown: { color: "var(--enarratio-status-unknown)", word: "unknown" },
77};
78
79/** An event with its times read and checked, and its window position clipped to the window. */
80interface PreparedEvent {
81  readonly lane: string;
82  readonly label: string;
83  readonly status: TimelineStatus;
84  readonly from: number;
85  readonly to: number;
86  readonly span: boolean;
87  /** `from` and `to` as text, using the options' formatter. */
88  readonly fromText: string;
89  readonly toText: string;
90  /** The event as one phrase of when: "2026-06-09 08:00 UTC" or "from ... to ...". */
91  readonly when: string;
92}
93
94/** Everything the timeline, its text alternative and its companion table are computed from. */
95interface TimelineValues {
96  readonly events: readonly PreparedEvent[];
97  readonly lanes: readonly string[];
98  readonly start: number;
99  readonly end: number;
100  readonly width: number;
101  readonly summary: string;
102  readonly alt: string;
103  readonly subject: string;
104}
105
106function readTime(what: string, value: unknown): number {
107  const date = toDate(value);
108  if (!date) {
109    throw new Error(`${KIND}: ${what} is ${JSON.stringify(value)}, not a time`);
110  }
111  return date.getTime();
112}
113
114/** Validates the options and computes the numbers every part of a timeline is made from. */
115function prepareTimeline(options: TimelineOptions): TimelineValues {
116  const { events } = options;
117  if (events.length === 0) throw new Error(`${KIND}: needs at least one event`);
118  const subject = options.label?.trim() ?? "";
119  const given = options.alt?.trim() ?? "";
120  if (subject === "" && given === "") throw new Error(`${KIND}: label or alt is required`);
121  const width = options.width ?? DEFAULT_WIDTH;
122  requireSize(KIND, "width", width);
123  const text = options.formatTime ?? formatInstant;
124  const at = (ms: number): string => text(new Date(ms));
125
126  const raw = events.map((event, i) => {
127    const n = `event ${i + 1}`;
128    if (typeof event.lane !== "string" || event.lane === "") {
129      throw new Error(`${KIND}: ${n} needs a lane`);
130    }
131    if (typeof event.label !== "string" || event.label.trim() === "") {
132      throw new Error(`${KIND}: ${n} needs a label`);
133    }
134    // Own properties only: "constructor" or "toString" from JSON is not a status.
135    if (typeof event.status !== "string" || !Object.hasOwn(STATUSES, event.status)) {
136      throw new Error(`${KIND}: ${n} has unknown status "${String(event.status)}"`);
137    }
138    const span = event.from !== undefined || event.to !== undefined;
139    if (span && event.at !== undefined) {
140      throw new Error(`${KIND}: ${n} has both a time (at) and a span (from, to)`);
141    }
142    if (span) {
143      if (event.from === undefined || event.to === undefined) {
144        throw new Error(`${KIND}: ${n} needs both from and to for a span`);
145      }
146      const from = readTime(`${n} from`, event.from);
147      const to = readTime(`${n} to`, event.to);
148      if (to < from) throw new Error(`${KIND}: ${n} ends before it starts`);
149      return { event, from, to, span };
150    }
151    if (event.at === undefined) throw new Error(`${KIND}: ${n} needs a time (at) or a span`);
152    const t = readTime(`${n} at`, event.at);
153    return { event, from: t, to: t, span };
154  });
155
156  const start =
157    options.start === undefined ? Number.POSITIVE_INFINITY : readTime("start", options.start);
158  const end = options.end === undefined ? Number.NEGATIVE_INFINITY : readTime("end", options.end);
159  const windowStart = options.start === undefined ? minOf(raw.map((r) => r.from)) : start;
160  const windowEnd = options.end === undefined ? maxOf(raw.map((r) => r.to)) : end;
161  if (!(windowEnd > windowStart)) {
162    throw new Error(
163      `${KIND}: the time window has no length (${at(windowStart)} to ${at(windowEnd)}); give start and end`,
164    );
165  }
166
167  const lanes = options.lanes ? [...options.lanes] : [...new Set(events.map((e) => e.lane))];
168  if (new Set(lanes).size !== lanes.length) throw new Error(`${KIND}: lanes has a repeated name`);
169  const prepared = raw.map(({ event, from, to, span }, i): PreparedEvent => {
170    if (!lanes.includes(event.lane)) {
171      throw new Error(`${KIND}: event ${i + 1} is in lane "${event.lane}", which lanes leaves out`);
172    }
173    if (to < windowStart || from > windowEnd) {
174      throw new Error(
175        `${KIND}: event ${i + 1} ("${event.label}") lies outside the time window ${at(windowStart)} to ${at(windowEnd)}`,
176      );
177    }
178    return {
179      lane: event.lane,
180      label: event.label,
181      status: event.status,
182      from,
183      to,
184      span,
185      fromText: at(from),
186      toText: at(to),
187      when: span ? `from ${at(from)} to ${at(to)}` : at(from),
188    };
189  });
190
191  const counts: Record<TimelineStatus, number> = { ok: 0, warning: 0, error: 0, unknown: 0 };
192  for (const e of prepared) counts[e.status] += 1;
193  const parts = (Object.keys(counts) as TimelineStatus[])
194    .filter((s) => counts[s] > 0)
195    .map((s) => `${counts[s]} ${STATUSES[s].word}`);
196  const laneCount = new Set(prepared.map((e) => e.lane)).size;
197  const summary = `${subject === "" ? "" : `${subject}: `}${defaultFormat(prepared.length)} ${prepared.length === 1 ? "event" : "events"} in ${laneCount} ${laneCount === 1 ? "lane" : "lanes"}, ${at(windowStart)} to ${at(windowEnd)}; ${parts.join(", ")}.`;
198  return {
199    events: prepared,
200    lanes,
201    start: windowStart,
202    end: windowEnd,
203    width,
204    summary,
205    alt: given || summary,
206    subject,
207  };
208}
209
210/** Events in time order, ties by lane: the order of the plain list and the table. */
211function sortedEvents(events: readonly PreparedEvent[]): PreparedEvent[] {
212  return [...events].sort(
213    (a, b) => a.from - b.from || (a.lane < b.lane ? -1 : a.lane > b.lane ? 1 : 0),
214  );
215}
216
217const ROW = 18;
218const LANE_PAD = 10;
219const TOP = 6;
220const AXIS = 26;
221const RIGHT = 16;
222const CHAR_WIDTH = 6.6;
223const MARKER = 6;
224const SPAN_HEIGHT = 8;
225
226const round = (n: number): number => Math.round(n * 100) / 100;
227const pad = (n: number): string => String(n).padStart(2, "0");
228
229/** Tick times (epoch milliseconds) and their labels, about six, aligned to UTC calendar units. */
230function ticks(start: number, end: number): { at: number; label: string }[] {
231  const MINUTE = 60_000;
232  const fixed = [1, 5, 15, 30, 60, 180, 360, 720, 1440, 2880, 10_080].map((m) => m * MINUTE);
233  const span = end - start;
234  const step = fixed.find((s) => span / s <= 7);
235  const out: { at: number; label: string }[] = [];
236  if (step !== undefined) {
237    for (let t = Math.ceil(start / step) * step; t <= end; t += step) {
238      const d = new Date(t);
239      const midnight = t % DAY === 0;
240      out.push({
241        at: t,
242        label:
243          step >= DAY
244            ? d.toISOString().slice(5, 10)
245            : midnight
246              ? d.toISOString().slice(5, 10)
247              : `${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}`,
248      });
249    }
250    return out;
251  }
252  // Longer than about seven weeks: whole calendar months, quarters, half years or years.
253  const first = new Date(start);
254  for (const months of [1, 3, 6, 12, 24, 60, 120]) {
255    const list: number[] = [];
256    let t = Date.UTC(first.getUTCFullYear(), Math.ceil(first.getUTCMonth() / months) * months, 1);
257    while (t <= end) {
258      list.push(t);
259      const d = new Date(t);
260      t = Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + months, 1);
261    }
262    if (list.length <= 7) {
263      return list.map((at) => ({
264        at,
265        label: new Date(at).toISOString().slice(0, months >= 12 ? 4 : 7),
266      }));
267    }
268  }
269  return out;
270}
271
272/** The shape that says a status without color: circle, triangle, square, hollow dashed circle. */
273function marker(status: TimelineStatus, cx: number, cy: number): string {
274  const color = STATUSES[status].color;
275  const ring = { stroke: "var(--enarratio-background)", "stroke-width": 1.5 };
276  switch (status) {
277    case "ok":
278      return element("circle", { cx, cy, r: 5, fill: color, ...ring });
279    case "warning":
280      return element("polygon", {
281        points: `${cx},${cy - MARKER} ${cx + MARKER},${cy + 5} ${cx - MARKER},${cy + 5}`,
282        fill: color,
283        ...ring,
284      });
285    case "error":
286      return element("rect", {
287        x: cx - 4.5,
288        y: cy - 4.5,
289        width: 9,
290        height: 9,
291        fill: color,
292        ...ring,
293      });
294    case "unknown":
295      return element("circle", {
296        cx,
297        cy,
298        r: 4.5,
299        fill: "var(--enarratio-background)",
300        stroke: color,
301        "stroke-width": 1.5,
302        "stroke-dasharray": "2,1.5",
303      });
304  }
305}
306
307/**
308 * An event timeline: one lane for each site, agent or service, with spans (things that lasted) and
309 * point events over a time window. Status is carried by the theme's status colors and by shape (a
310 * circle for ok, a triangle for warning, a square for error, a dashed hollow circle for unknown),
311 * so it reads without hue. Events that overlap in a lane stack in rows.
312 *
313 * The result is a container: the drawing, named by its text alternative, and a plain list of the
314 * same events. With stylesheet or `enarratio/base.css`, the list is read by screen readers beside
315 * the drawing, and replaces it when there is less than 30rem of room. Without CSS both show.
316 *
317 * @example
318 * timeline({
319 *   label: "Agent runs",
320 *   events: [
321 *     { lane: "Agent A", label: "Nightly run", status: "ok", from: "2026-06-09T01:00Z", to: "2026-06-09T02:10Z" },
322 *     { lane: "Agent B", label: "Timeout", status: "error", at: "2026-06-09T03:30Z" },
323 *   ],
324 * });
325 */
326export function timeline(options: TimelineOptions): string {
327  const p = prepareTimeline(options);
328  const longest = Math.max(maxOf(p.lanes.map((l) => l.length)), 1);
329  const left = Math.round(Math.min(180, Math.max(64, longest * CHAR_WIDTH + 20)));
330  const plotWidth = Math.max(40, p.width - left - RIGHT);
331  const xOf = (t: number): number =>
332    round(
333      left + (Math.min(Math.max(t, p.start), p.end) - p.start) * (plotWidth / (p.end - p.start)),
334    );
335
336  // Pack each lane's events into rows so overlapping ones do not draw over each other.
337  const packed = p.lanes.map((lane) => {
338    const own = p.events.filter((e) => e.lane === lane).sort((a, b) => a.from - b.from);
339    const rowEnds: number[] = [];
340    const placed = own.map((event) => {
341      const a = xOf(event.from) - MARKER - 1;
342      const b = event.span ? xOf(event.to) + 2 : xOf(event.from) + MARKER + 1;
343      let row = rowEnds.findIndex((end) => end <= a);
344      if (row === -1) row = rowEnds.length;
345      rowEnds[row] = b;
346      return { event, row };
347    });
348    return { lane, placed, rows: Math.max(1, rowEnds.length) };
349  });
350  const laneTop: number[] = [];
351  let y = TOP;
352  for (const lane of packed) {
353    laneTop.push(y);
354    y += lane.rows * ROW + LANE_PAD;
355  }
356  const plotBottom = y;
357  const height = plotBottom + AXIS;
358  const axis = ticks(p.start, p.end);
359
360  const maxChars = Math.floor((left - 12) / CHAR_WIDTH);
361  const parts: string[] = [element("title", {}, escapeHtml(p.alt))];
362  // Gridlines first, then lane labels, so marks draw over them.
363  for (const t of axis) {
364    const x = xOf(t.at);
365    parts.push(
366      element("line", {
367        x1: x,
368        x2: x,
369        y1: TOP,
370        y2: plotBottom,
371        stroke: "var(--enarratio-grid)",
372        "stroke-width": 1,
373      }),
374      element(
375        "text",
376        {
377          x,
378          y: plotBottom + 16,
379          "text-anchor": "middle",
380          fill: "var(--enarratio-text-muted)",
381          class: "enarratio-numeric",
382        },
383        escapeHtml(t.label),
384      ),
385    );
386  }
387  packed.forEach((lane, i) => {
388    const top = laneTop[i] as number;
389    const mid = top + (lane.rows * ROW + LANE_PAD) / 2;
390    const shown = lane.lane.length > maxChars ? `${lane.lane.slice(0, maxChars - 1)}…` : lane.lane;
391    parts.push(
392      element("line", {
393        x1: left,
394        x2: left + plotWidth,
395        y1: top + lane.rows * ROW + LANE_PAD,
396        y2: top + lane.rows * ROW + LANE_PAD,
397        stroke: "var(--enarratio-grid)",
398        "stroke-width": 1,
399      }),
400      element(
401        "text",
402        {
403          x: left - 8,
404          y: mid,
405          "text-anchor": "end",
406          "dominant-baseline": "central",
407          fill: "var(--enarratio-text)",
408        },
409        `${escapeHtml(shown)}${shown === lane.lane ? "" : element("title", {}, escapeHtml(lane.lane))}`,
410      ),
411    );
412    for (const { event, row } of lane.placed) {
413      const cy = top + LANE_PAD / 2 + row * ROW + ROW / 2;
414      const title = element(
415        "title",
416        {},
417        escapeHtml(`${event.lane}: ${event.label}, ${STATUSES[event.status].word}, ${event.when}`),
418      );
419      const x0 = xOf(event.from);
420      const bar = event.span
421        ? element("rect", {
422            x: x0,
423            y: cy - SPAN_HEIGHT / 2,
424            width: Math.max(2, round(xOf(event.to) - x0)),
425            height: SPAN_HEIGHT,
426            rx: 2,
427            fill: event.status === "unknown" ? "none" : STATUSES[event.status].color,
428            ...(event.status === "unknown"
429              ? { stroke: STATUSES.unknown.color, "stroke-dasharray": "3,2" }
430              : {}),
431          })
432        : "";
433      parts.push(
434        element(
435          "g",
436          { "data-enarratio-mark": "event", "data-status": event.status },
437          `${title}${bar}${marker(event.status, x0, cy)}`,
438        ),
439      );
440    }
441  });
442
443  const svg = element(
444    "svg",
445    {
446      xmlns: "http://www.w3.org/2000/svg",
447      viewBox: `0 0 ${p.width} ${height}`,
448      width: p.width,
449      height,
450      role: "img",
451      "aria-label": p.alt,
452    },
453    parts.join(""),
454  );
455  const list = element(
456    "ol",
457    { class: "enarratio-timeline-list" },
458    sortedEvents(p.events)
459      .map((e) =>
460        element(
461          "li",
462          {},
463          `<strong>${escapeHtml(e.lane)}</strong>: ${escapeHtml(e.label)}, ${STATUSES[e.status].word}, ${escapeHtml(e.when)}`,
464        ),
465      )
466      .join(""),
467  );
468  return element(
469    "div",
470    { class: "enarratio enarratio-timeline", "data-enarratio": "timeline" },
471    `${svg}${list}`,
472  );
473}
474
475/**
476 * A timeline's events as a table (event, lane, status, start and end, the end blank for a point
477 * event) in time order, and a summary sentence with the counts, computed from the same events
478 * as the drawing and its plain list so they cannot disagree. Takes the same options as
479 * {@link timeline}. Without `label` the summary is the given `alt`.
480 *
481 * @example
482 * const { table } = timelineTable({ label: "Agent runs", events });
483 */
484export function timelineTable(
485  options: TimelineOptions,
486  display?: PrimitiveTableOptions,
487): PrimitiveTable {
488  const p = prepareTimeline(options);
489  return primitiveTable(
490    p.summary,
491    {
492      columns: ["Event", "Lane", "Status", "Start", "End"],
493      rows: sortedEvents(p.events).map((e) => [
494        e.label,
495        e.lane,
496        STATUSES[e.status].word,
497        e.fromText,
498        e.span ? e.toText : "",
499      ]),
500    },
501    p.subject || p.alt,
502    display,
503  );
504}