ui/timeline.tsx

GitHub
'use client';

import * as React from 'react';
import {useVirtualizer} from '@tanstack/react-virtual';
import {durationUnitFor, formatDurations} from '../lib/data';
import {cn} from '../lib/utils';
import {niceScale} from './chart-scale';
import {Skeleton} from './skeleton';
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;
  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;
  maxHeight?: number;
  loading?: boolean;
  footer?: React.ReactNode;
  frame?: 'card' | 'none';
};

const ROW = 36;
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, maxHeight, loading = false, footer, frame = 'card', 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).map(t => t * unitSize);
  const frac = (ms: number) => Math.min(Math.max(ms, 0), total) / total;
  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 / unitSize).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 waiting = spans.some(s => s.status === 'waiting');
  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, 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 focusRow = (index: number) => {
    const next = Math.max(0, Math.min(spans.length - 1, index));
    setFocusIndex(next);
    if (windowed) virtualizer.scrollToIndex(next, {align: 'auto'});
    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 marked = spans.some(s => s.status === 'warn' || s.status === 'fail' || s.status === 'waiting');
  const columns = cn(
    'grid items-center grid-cols-[minmax(0,2fr)_minmax(0,3fr)] @xl/timeline:grid-cols-[minmax(0,var(--label-col))_minmax(0,1fr)]',
    marked && '@xl/timeline:grid-cols-[minmax(0,var(--label-col))_minmax(0,1fr)_auto]',
  );
  const glide = running ? 'transition-[inset-inline-start,width] duration-1000 ease-linear motion-reduce:transition-none' : '';
  const gridlines = ticks.slice(1).filter(t => frac(t) <= 0.92).map(t => <span key={t} aria-hidden className="absolute inset-y-0 w-px bg-line-faint" style={{insetInlineStart: at(t)}}/>);

  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 labelPx = durations[index].length * 6.5 + (s.status === 'waiting' ? (statusWord(s).length + 2) * 6.5 : 0);
    const place: 'after' | 'before' | 'name' = trackPx === 0 ? (frac(end) <= 0.84 ? 'after' : 'before')
      : (1 - frac(end)) * trackPx >= labelPx + 8 ? 'after'
      : frac(s.start) * trackPx >= labelPx + 8 ? 'before' : 'name';
    const after = place === 'after';
    const durationTone = trouble === 'fail' ? 'text-fail-text' : trouble === 'warn' ? 'text-warn-text' : 'text-text-2';
    const durationText = <>
      <span className={cn(s.status === 'waiting' && marked && '@max-xl/timeline:hidden')}>{durations[index]}</span>
      {s.status === 'waiting' && <Status status="waiting" size="sm" className="@xl/timeline:hidden">{statusWord(s)}</Status>}
    </>;
    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()}` : ''}`;
    const depth = s.depth ?? 0;
    return <div
      key={s.id}
      data-index={index}
      data-slot="timeline-row"
      data-status={trouble ?? (s.status === 'waiting' ? 'waiting' : undefined)}
      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, 'h-(--row) border-b border-line-faint transition-colors duration-(--dur-state) ease-out last:border-b-0',
        open && 'bg-pressed',
        onSpanClick && 'cursor-pointer focus-visible:focus-ring-inset', onSpanClick && !open && 'hover:bg-hover',
        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-full min-w-0 items-center gap-2 pe-3" style={{paddingInlineStart: `calc(var(--space-3) + ${depth} * var(--space-3))`}}>
        {Array.from({length: depth}, (_, d) => <span key={d} data-slot="timeline-guide" className="absolute inset-y-0 w-px bg-line" style={{insetInlineStart: `calc(var(--space-3) + ${d} * var(--space-3) + var(--space-1))`}}/>)}
        <span className="min-w-16 truncate type-label text-text-1">{s.label}</span>
        {s.meta != null && <span className="min-w-0 shrink truncate type-code-xs text-text-2 @max-lg/timeline:hidden">{s.meta}</span>}
        {place === 'name' && <span data-slot="timeline-duration" data-place="name" className={cn('ms-auto flex shrink-0 items-center gap-1 whitespace-nowrap type-caption data', durationTone)}>{durationText}</span>}
        {s.figure != null && place !== 'name' && <span data-slot="timeline-figure" className="ms-auto shrink-0 type-caption data text-text-2 @max-md/timeline:hidden @max-[12rem]/name:hidden">{s.figure}</span>}
      </span>
      <span aria-hidden data-slot="timeline-track" className="relative me-3 h-full">
        {gridlines}
        {s.status === 'waiting'
          ? <span data-slot="timeline-wait" className={cn('absolute top-1/2 h-3 min-w-3 -translate-y-1/2 rounded-pill border border-dashed border-text-2 bg-paper', glide)} style={{insetInlineStart: at(s.start), width: `calc(${at(end)} - ${at(s.start)})`}}/>
          : <span
              data-slot="timeline-bar"
              data-status={trouble}
              className={cn(
                'absolute top-1/2 h-3 min-w-1 -translate-y-1/2 rounded-pill forced-colors:bg-[CanvasText]',
                trouble === 'fail' ? 'bg-fail' : trouble === 'warn' ? 'bg-warn' : open ? 'bg-ink' : 'bg-line-strong',
                glide,
              )}
              style={{insetInlineStart: at(s.start), width: `calc(${at(end)} - ${at(s.start)})`}}
            />}
        {place !== 'name' && <span
          data-slot="timeline-duration"
          data-place={place}
          className={cn('absolute top-1/2 flex -translate-y-1/2 items-center gap-1 whitespace-nowrap type-caption data', durationTone, glide)}
          style={after ? {insetInlineStart: `calc(${at(end)} + var(--space-2))`} : {insetInlineEnd: `calc(100% - ${at(s.start)} + var(--space-2))`}}
        >{durationText}</span>}
      </span>
      {marked && <span aria-hidden className="hidden justify-end pe-3 @xl/timeline:flex">
        {s.status === 'waiting'
          ? <Status status="waiting" size="sm">{statusWord(s)}</Status>
          : trouble && <Status status={trouble} size="sm">{statusWord(s)}</Status>}
      </span>}
    </div>;
  };

  const panel = <>
    <header data-slot="timeline-header" className="flex min-h-(--row) min-w-0 items-center gap-2 border-b border-line-faint px-3">
      <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-2 data">{totalLabel}</span>}
      <span className="ms-auto shrink-0">
        {failed ? <Status status="fail" size="sm">Failed</Status> : waiting ? <Status status="waiting" size="sm"/> : running ? <Status status="running" size="sm"/> : spans.length > 0 && !loading ? <Status status="ok" size="sm"/> : null}
      </span>
    </header>
    <div aria-hidden className={cn(columns, 'h-8 shrink-0 border-b border-line-faint')}>
      <span className="ps-3 type-label-sm text-text-2">Step</span>
      <span ref={trackRef} className="relative me-3 h-full">
        {!loading && spans.length > 0 && ticks.map((t, i) => <span key={t} className={cn('absolute top-1/2 -translate-y-1/2 type-caption text-text-2 data', i > 0 && '-translate-x-1/2 rtl:translate-x-1/2', frac(t) > 0.92 && 'hidden')} style={{insetInlineStart: at(t)}}>{tickLabels[i]}</span>)}
      </span>
      {marked && <span className="hidden @xl/timeline:block"/>}
    </div>
    <div
      ref={scrollRef}
      role={onSpanClick ? 'listbox' : 'list'}
      aria-label={`Steps in ${label}`}
      className="relative min-h-0 overflow-auto overscroll-contain"
      style={maxHeight ? {maxHeight} : undefined}
    >
      {loading
        ? Array.from({length: 4}, (_, i) => <div key={i} aria-hidden className={cn(columns, 'h-(--row) border-b border-line-faint last:border-b-0')}>
            <span className="ps-3"><Skeleton className="h-2 w-2/3 rounded-pill"/></span>
            <span className="relative me-3 h-full"><Skeleton className="absolute top-1/2 h-3 -translate-y-1/2 rounded-pill" style={{insetInlineStart: `${i * 18}%`, width: `${30 - i * 4}%`}}/></span>
          </div>)
        : spans.length === 0
          ? <p className="px-3 py-4 type-body-sm 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>
    <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>
  </>;

  return <section
    data-slot="timeline"
    data-status={failed ? 'fail' : undefined}
    data-frame={frame}
    aria-label={label}
    aria-busy={loading || undefined}
    className={cn('@container/timeline flex min-w-0 flex-col text-text-1', frame === 'card' && 'shell forced-colors:border-[CanvasText]', className)}
    {...props}
  >
    {frame === 'card'
      ? <div data-slot="timeline-panel" className="panel flex min-w-0 flex-col overflow-hidden forced-colors:border-[CanvasText]">{panel}</div>
      : panel}
    {footer != null && <div data-slot="timeline-footer" className={frame === 'card' ? 'shell-foot' : 'flex min-h-(--row) items-center gap-2 border-t border-line-faint px-3 type-caption text-text-2'}>{footer}</div>}
  </section>;
}

export {Timeline, type TimelineProps, type TimelineSpan, type TimelineStatus};