ui/timeline.tsx
GitHub'use client';
import * as React from 'react';
import {useVirtualizer} from '@tanstack/react-virtual';
import type {Kind} from '../lib/kind';
import {durationUnitFor, formatDurations} from '../lib/format';
import {useOffscreen} from '../lib/use-offscreen';
import {cn} from '../lib/utils';
import {niceScale} from './chart-scale';
import {Status, statusLabels} from './status';
type TimelineStatus = 'queued' | 'running' | 'ok' | 'warn' | 'fail' | 'waiting';
type TimelineSpan = {
id: string;
label: string;
start: number;
end?: number;
status?: TimelineStatus;
waitingLabel?: string;
kind?: Kind;
depth?: number;
meta?: React.ReactNode;
figure?: React.ReactNode;
};
type TimelineProps = Omit<React.ComponentProps<'section'>, 'children'> & {
label: string;
spans: TimelineSpan[];
now?: number;
activeId?: string;
onSpanClick?: (span: TimelineSpan) => void;
kind?: Kind;
maxHeight?: number;
loading?: boolean;
bars?: 'kind' | 'quiet';
footer?: React.ReactNode;
size?: 'default' | 'sm';
};
const ROW = {default: 40, sm: 32} as const;
const WINDOW_FROM = 200;
const statusWord = (s: TimelineSpan) => (s.status === 'waiting' ? s.waitingLabel ?? statusLabels.waiting : s.status ? statusLabels[s.status] : '');
function Timeline({label, spans, now, activeId, onSpanClick, kind, maxHeight, loading = false, bars = 'kind', footer, size = 'default', className, ...props}: TimelineProps) {
const ends = spans.map(s => s.end ?? now ?? s.start);
const total = Math.max(1, ...ends, now ?? 0);
const {unit, size: unitSize} = durationUnitFor([total]);
const unitScale = niceScale(0, total / unitSize, 4);
const ticks = unitScale.ticks.filter(t => t * unitSize <= total + 1e-6);
const scale = {max: total, ticks: ticks.map(t => t * unitSize)};
const span = scale.max || 1;
const frac = (ms: number) => Math.min(Math.max(ms, 0), span) / span;
const at = (ms: number) => `${frac(ms) * 100}%`;
const durations = formatDurations(spans.map((s, i) => ends[i] - s.start)).values;
const tickLabels = ticks.map(t => `${t.toLocaleString('en-US')}${unit}`);
const totalLabel = formatDurations([total]).values[0];
const running = spans.some(s => s.status === 'running' || (s.end === undefined && s.status !== 'waiting' && s.status !== 'queued'));
const failed = spans.some(s => s.status === 'fail');
const frameRef = useOffscreen<HTMLElement>(running);
const scrollRef = React.useRef<HTMLDivElement>(null);
const windowed = !!maxHeight && spans.length >= WINDOW_FROM;
const virtualizer = useVirtualizer({count: windowed ? spans.length : 0, getScrollElement: () => scrollRef.current, estimateSize: () => ROW[size], overscan: 10});
const rows = windowed ? virtualizer.getVirtualItems().map(item => ({index: item.index, start: item.start})) : spans.map((_, index) => ({index, start: 0}));
const [focusIndex, setFocusIndex] = React.useState<number | null>(null);
const activeIndex = activeId === undefined ? -1 : spans.findIndex(s => s.id === activeId);
const tabRow = focusIndex ?? Math.max(activeIndex, 0);
const trackRef = React.useRef<HTMLSpanElement>(null);
const [trackPx, setTrackPx] = React.useState(0);
React.useEffect(() => {
const el = trackRef.current;
if (!el) return;
const measure = () => setTrackPx(el.clientWidth);
measure();
const observer = new ResizeObserver(measure);
observer.observe(el);
return () => observer.disconnect();
}, []);
const show = (index: number) => {
if (windowed) virtualizer.scrollToIndex(index, {align: 'center'});
else scrollRef.current?.querySelector<HTMLElement>(`[data-index="${index}"]`)?.scrollIntoView({block: 'nearest'});
};
const focusRow = (index: number) => {
const next = Math.max(0, Math.min(spans.length - 1, index));
setFocusIndex(next);
show(next);
requestAnimationFrame(() => scrollRef.current?.querySelector<HTMLElement>(`[data-index="${next}"]`)?.focus());
};
const onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>, index: number) => {
const moves: Record<string, number> = {ArrowDown: index + 1, ArrowUp: index - 1, Home: 0, End: spans.length - 1};
if (event.key in moves) { event.preventDefault(); focusRow(moves[event.key]); return; }
if ((event.key === 'Enter' || event.key === ' ') && !event.repeat) { event.preventDefault(); onSpanClick?.(spans[index]); }
};
const step = scale.ticks.length > 1 ? scale.ticks[1] - scale.ticks[0] : span;
const grid = {backgroundImage: 'linear-gradient(to right, var(--line-row) var(--line-hair), transparent var(--line-hair))', backgroundSize: `${(step / span) * 100}% 100%`} as React.CSSProperties;
const marked = spans.some(s => s.status === 'warn' || s.status === 'fail' || s.status === 'waiting');
const columns = cn('grid items-center grid-cols-[minmax(0,max(var(--timeline-name-min),40%))_minmax(0,1fr)]', marked
? '@xl/timeline:grid-cols-[minmax(0,clamp(var(--timeline-name-min),30%,var(--timeline-name)))_minmax(0,1fr)_var(--status-column)]'
: '@xl/timeline:grid-cols-[minmax(0,clamp(var(--timeline-name-min),30%,var(--timeline-name)))_minmax(0,1fr)]');
const glide = running ? 'transition-[inset-inline-start,inset-inline-end,width] duration-1000 ease-linear motion-reduce:transition-none' : '';
const row = (index: number, top: number) => {
const s = spans[index];
const end = ends[index];
const open = s.id === activeId;
const trouble = s.status === 'warn' || s.status === 'fail' ? s.status : undefined;
const isRunning = s.end === undefined && s.status !== 'waiting' && s.status !== 'queued';
const charPx = 6.5;
const labelPx = durations[index].length * charPx + (s.status === 'waiting' ? (statusWord(s).length + 2) * charPx : 0);
const gap = 8;
const barPx = (frac(end) - frac(s.start)) * trackPx;
const place: 'in' | 'after' | 'before' = trackPx === 0
? (s.status !== 'waiting' && frac(end) - frac(s.start) >= 0.22 ? 'in' : frac(end) <= 0.84 ? 'after' : 'before')
: s.status !== 'waiting' && barPx >= labelPx + gap * 2 ? 'in'
: (1 - frac(end)) * trackPx >= labelPx + gap ? 'after'
: 'before';
const colored = bars === 'kind' || open || !!trouble;
const name = `${s.label}, started at ${formatDurations([s.start]).values[0]}, ${isRunning || s.status === 'waiting' ? 'so far' : 'took'} ${durations[index]}${s.status && s.status !== 'ok' ? `, ${statusWord(s).toLowerCase()}` : ''}`;
return <div
key={s.id}
data-index={index}
data-slot="timeline-row"
data-kind={s.kind}
data-status={trouble}
data-open={open || undefined}
role={onSpanClick ? 'option' : 'listitem'}
aria-selected={onSpanClick ? open : undefined}
aria-label={name}
tabIndex={onSpanClick ? (index === tabRow ? 0 : -1) : undefined}
onFocus={onSpanClick ? () => setFocusIndex(index) : undefined}
onKeyDown={onSpanClick ? event => onKeyDown(event, index) : undefined}
onClick={onSpanClick ? () => onSpanClick(s) : undefined}
className={cn(
columns, 'min-h-(--timeline-row) rule-row transition-colors duration-(--dur-fast) ease-(--ease-step)',
trouble === 'fail' && 'wash-row',
onSpanClick && 'cursor-pointer hover:bg-hover focus-visible:focus-ring-inset',
windowed && 'absolute inset-x-0 top-0',
)}
style={windowed ? {transform: `translateY(${top}px)`} : undefined}
>
<span aria-hidden data-slot="timeline-name" className="@container/name relative flex h-(--timeline-row) min-w-0 items-center gap-2 ps-4 pe-3" style={{paddingInlineStart: `calc(var(--space-4) + ${s.depth ?? 0} * var(--space-4))`}}>
{Array.from({length: s.depth ?? 0}, (_, d) => <span key={d} data-slot="timeline-guide" className="absolute inset-y-0 w-px bg-line-row" style={{insetInlineStart: `calc(var(--space-4) + ${d} * var(--space-4) + var(--space-1))`}}/>)}
<span className="min-w-(--timeline-label-min) truncate type-label text-text-1">{s.label}</span>
{s.meta != null && <span className="min-w-0 shrink truncate type-tag text-text-3 @max-md/timeline:hidden">{s.meta}</span>}
{s.figure != null && <span data-slot="timeline-figure" className="ms-auto shrink-0 type-tag data text-text-3 @max-md/timeline:hidden @max-[16rem]/name:hidden">{s.figure}</span>}
</span>
<span aria-hidden data-slot="timeline-track" className="relative me-4 h-(--timeline-row)" style={grid}>
{s.status === 'waiting'
? <span data-slot="timeline-wait" className={cn('absolute top-1/2 h-4 -translate-y-1/2 rounded-inner bg-page control-edge [--frame-color:var(--ink)]', glide)} style={{insetInlineStart: at(s.start), width: `calc(${at(end)} - ${at(s.start)})`, minWidth: 'var(--space-1)'}}/>
: <span data-slot="timeline-bar" data-status={trouble} data-kind={bars === 'quiet' && open && !trouble ? kind ?? 'run' : undefined} className={cn('absolute top-1/2 h-4 -translate-y-1/2 rounded-inner forced-colors:bg-[CanvasText]', colored ? 'bg-accent-mark' : 'bg-(--line-control-hover)', glide)} style={{insetInlineStart: at(s.start), width: `calc(${at(end)} - ${at(s.start)})`, minWidth: 'var(--space-1)'}}/>}
<span
data-slot="timeline-duration"
data-place={place}
className={cn(
'absolute top-1/2 -translate-y-1/2 whitespace-nowrap type-label-sm data',
place === 'in' ? (colored ? 'text-on-field' : 'text-text-1') : trouble === 'fail' ? 'text-fail-text' : trouble === 'warn' ? 'text-warn-text' : 'text-text-2',
glide,
)}
style={place === 'after'
? {insetInlineStart: `calc(${at(end)} + var(--space-2))`}
: {insetInlineEnd: `calc(100% - ${at(place === 'in' ? end : s.start)} + var(--space-2))`}}
>
<span className={cn(s.status === 'waiting' && '@max-xl/timeline:hidden')}>{durations[index]}</span>
{s.status === 'waiting' && <Status status="waiting" className="type-label-sm @xl/timeline:hidden">{statusWord(s)}</Status>}
</span>
</span>
<span aria-hidden className="flex justify-end pe-4 empty:hidden @max-xl/timeline:hidden">
{s.status === 'waiting'
? <Status status="waiting" className="type-label-sm">{statusWord(s)}</Status>
: trouble && <Status status={trouble} className="type-label-sm">{statusWord(s)}</Status>}
</span>
</div>;
};
return <section
ref={frameRef}
data-slot="timeline"
data-kind={kind}
data-status={failed ? 'fail' : undefined}
aria-label={label}
aria-busy={loading || undefined}
data-size={size}
className={cn('@container/timeline frame flex min-w-0 flex-col bg-page text-text-1 [--timeline-row:var(--row)] data-[size=sm]:[--timeline-row:var(--row-sm)]', className)}
{...props}
>
<header data-slot="timeline-header" className="frame-head rule-row">
<span className="min-w-0 truncate type-label text-text-1">{label}</span>
{!loading && spans.length > 0 && <span className="shrink-0 type-label text-text-3 data">{totalLabel}</span>}
<span className="frame-head-action">
{failed ? <Status status="fail">Failed</Status> : running && <Status status="running"/>}
</span>
</header>
<div data-slot="timeline-inset" className="flex min-h-0 min-w-0 flex-col">
<div aria-hidden className={cn(columns, 'h-(--row-sm) shrink-0 rule-row')}>
<span className="ps-4 type-label-sm text-text-3">Step</span>
<span ref={trackRef} className="relative me-4 h-full">
{scale.ticks.map((t, i) => <span key={t} className={cn('absolute top-1/2 -translate-y-1/2 type-label-sm text-text-3 data', i > 0 && '-translate-x-1/2 rtl:translate-x-1/2', scale.ticks[i] / span > 0.92 && 'hidden')} style={{insetInlineStart: at(t)}}>{tickLabels[i]}</span>)}
</span>
<span className="@max-xl/timeline:hidden"/>
</div>
<div className="relative min-h-0">
<div
ref={scrollRef}
role={onSpanClick ? 'listbox' : 'list'}
aria-label={`Steps in ${label}`}
className="relative overflow-auto overscroll-contain [scrollbar-width:thin]"
style={maxHeight ? {maxHeight} : undefined}
>
{loading
? Array.from({length: 4}, (_, i) => <div key={i} aria-hidden className={cn(columns, 'h-(--timeline-row) rule-row')}>
<span className="ps-4"><span className="block h-2 w-2/3 bg-(--surface-skeleton)"/></span>
<span className="relative h-full"><span className="absolute top-1/2 h-3 -translate-y-1/2 bg-(--surface-skeleton)" style={{insetInlineStart: `${i * 18}%`, width: `${30 - i * 4}%`}}/></span>
<span className="@max-xl/timeline:hidden"/>
</div>)
: spans.length === 0
? <p className="px-4 py-6 type-body text-text-2">No steps yet.</p>
: windowed
? <div className="relative" style={{height: virtualizer.getTotalSize()}}>{rows.map(r => row(r.index, r.start))}</div>
: rows.map(r => row(r.index, 0))}
</div>
</div>
</div>
{footer != null && <div data-slot="timeline-footer" className={'shrink-0 rule-top'}>{footer}</div>}
<table className="sr-only">
<caption>{label}</caption>
<thead><tr><th scope="col">Step</th><th scope="col">Started at</th><th scope="col">Took</th><th scope="col">Status</th></tr></thead>
<tbody>{spans.map((s, i) => <tr key={s.id}><th scope="row">{s.label}</th><td>{formatDurations([s.start]).values[0]}</td><td>{durations[i]}</td><td>{statusWord(s) || statusLabels.ok}</td></tr>)}</tbody>
</table>
</section>;
}
export {Timeline, type TimelineProps, type TimelineSpan, type TimelineStatus};