@spunto/design-system 0.33.0 → 0.35.0

package/src/components/observability/span-waterfall.tsx

@@ -0,0 +1,493 @@
+"use client"
+
+import { useMemo, useState, type KeyboardEvent } from "react"
+import { ChevronRightIcon } from "lucide-react"
+import { cn } from "../../utils"
+import { formatLatency } from "./latency"
+import { LogLines, type TelemetryLogLine } from "./log-lines"
+import type { TraceSpan } from "./types"
+
+// ── Span waterfall ────────────────────────────────────────────────────────
+// A trace as a tree of spans on a shared time axis. Purely presentational: it takes the spans,
+// the app fetches them (and owns the loading/not-found states, which say things about *its*
+// backend). Click a row for its attributes.
+
+/**
+ * Colour of a span by what it is: agent RPC and jobs → run, database → ship, the rest (HTTP) →
+ * build, any error → destructive. Read from OTel semantic attributes first, from the span name
+ * as a fallback.
+ */
+export function spanColor(s: TraceSpan): string {
+  if (s.error) return "var(--destructive)"
+  const n = s.name.toLowerCase()
+  const attrs = s.attributes ?? {}
+  if (n.startsWith("agent.cmd") || attrs["rpc.system"]) return "var(--run)"
+  if (n.startsWith("pg") || n.startsWith("sqlite") || attrs["db.system"]) return "var(--ship)"
+  if (n.startsWith("job.") || n.startsWith("worker.spawn")) return "var(--run)"
+  return "var(--build)"
+}
+
+const LEGEND: [label: string, color: string][] = [
+  ["http", "var(--build)"],
+  ["db", "var(--ship)"],
+  ["agent rpc / job", "var(--run)"],
+]
+
+/**
+ * Depth-first order, children directly under their parent (a real tree, like Datadog) instead of
+ * the backend's start-time order which interleaves siblings' subtrees. Siblings by start time; a
+ * span whose parent isn't in the set is a root.
+ */
+export function orderSpans<S extends TraceSpan>(spans: S[]): { span: S; depth: number }[] {
+  const ids = new Set(spans.map((s) => s.spanId))
+  const byParent = new Map<string | null, S[]>()
+  for (const s of spans) {
+    const key = s.parentSpanId && ids.has(s.parentSpanId) ? s.parentSpanId : null
+    const arr = byParent.get(key)
+    if (arr) arr.push(s)
+    else byParent.set(key, [s])
+  }
+  for (const arr of byParent.values()) arr.sort((a, b) => a.startTimeMs - b.startTimeMs)
+  const out: { span: S; depth: number }[] = []
+  const seen = new Set<string>()
+  const walk = (parentId: string | null, depth: number) => {
+    for (const s of byParent.get(parentId) ?? []) {
+      // A malformed trace (a span listed as its own ancestor) must not loop forever.
+      if (seen.has(s.spanId)) continue
+      seen.add(s.spanId)
+      out.push({ span: s, depth })
+      walk(s.spanId, depth + 1)
+    }
+  }
+  walk(null, 0)
+  return out
+}
+
+/** Per span of an `orderSpans` result: its parent in the tree, and what folding it would hide. */
+export interface SpanTreeInfo {
+  parentId: string | null
+  /** Every span under it, at any depth. 0 = a leaf, nothing to fold. */
+  descendants: number
+  /** Whether one of those descendants is in error — so a folded row can still say so. */
+  descendantError: boolean
+}
+
+/** The tree `orderSpans` walked, indexed by span id. Linear: a subtree is a contiguous run. */
+export function spanTree(ordered: { span: TraceSpan; depth: number }[]): Map<string, SpanTreeInfo> {
+  const info = new Map<string, SpanTreeInfo>()
+  const stack: { id: string; depth: number }[] = []
+  for (const { span, depth } of ordered) {
+    while (stack.length && stack[stack.length - 1].depth >= depth) stack.pop()
+    info.set(span.spanId, { parentId: stack[stack.length - 1]?.id ?? null, descendants: 0, descendantError: false })
+    for (const a of stack) {
+      const ai = info.get(a.id)!
+      ai.descendants++
+      if (span.error) ai.descendantError = true
+    }
+    stack.push({ id: span.spanId, depth })
+  }
+  return info
+}
+
+export interface SpanWaterfallProps {
+  spans: TraceSpan[]
+  /** Shown in the header line, next to the span count and total duration. */
+  traceId?: string
+  /** Wider name column and one more attribute chip — for a fullscreen sheet. */
+  fullWidth?: boolean
+  /** Controlled selection. Omit both to let the component keep it. */
+  selectedSpanId?: string | null
+  onSelectedSpanChange?: (spanId: string | null) => void
+  /** Override the colour rule (default `spanColor`). */
+  colorOf?: (span: TraceSpan) => string
+  /**
+   * Folded spans (their subtree is hidden). Controlled with `onCollapsedSpanIdsChange`; omit both
+   * to let the component keep it.
+   */
+  collapsedSpanIds?: string[]
+  onCollapsedSpanIdsChange?: (spanIds: string[]) => void
+  /**
+   * Uncontrolled only: spans at this depth or deeper start folded (0 = only the roots show).
+   * For a trace of hundreds of spans, where the first screen should be the shape, not the leaves.
+   */
+  defaultCollapsedDepth?: number
+  /** The colour legend under the waterfall. Hide it when `colorOf` means something else. */
+  legend?: boolean
+  /**
+   * The log lines stamped with this trace id. Given (even empty), a Logs section is drawn under
+   * the waterfall: times relative to the trace start, a line tied to a span selects it, and the
+   * selected span's lines are highlighted.
+   */
+  logs?: TelemetryLogLine[]
+  /** While the app fetches `logs`, or when it couldn't. */
+  logsStatus?: "loading" | "error"
+  className?: string
+}
+
+export function SpanWaterfall({
+  spans,
+  traceId,
+  fullWidth = false,
+  selectedSpanId,
+  onSelectedSpanChange,
+  colorOf = spanColor,
+  legend = true,
+  collapsedSpanIds,
+  onCollapsedSpanIdsChange,
+  defaultCollapsedDepth,
+  logs,
+  logsStatus,
+  className,
+}: SpanWaterfallProps) {
+  const [ownSelected, setOwnSelected] = useState<string | null>(null)
+  const selected = selectedSpanId !== undefined ? selectedSpanId : ownSelected
+  const setSelected = (id: string | null) => {
+    if (selectedSpanId === undefined) setOwnSelected(id)
+    onSelectedSpanChange?.(id)
+  }
+
+  const ordered = useMemo(() => orderSpans(spans), [spans])
+  const tree = useMemo(() => spanTree(ordered), [ordered])
+
+  // Folding. Uncontrolled state is seeded once from `defaultCollapsedDepth`; a span id that isn't
+  // (or no longer is) a parent in this trace is simply ignored.
+  const [ownCollapsed, setOwnCollapsed] = useState<string[]>(() =>
+    defaultCollapsedDepth === undefined
+      ? []
+      : ordered.filter((o) => o.depth >= defaultCollapsedDepth && (tree.get(o.span.spanId)?.descendants ?? 0) > 0).map((o) => o.span.spanId)
+  )
+  const collapsedList = collapsedSpanIds ?? ownCollapsed
+  const collapsed = useMemo(() => new Set(collapsedList), [collapsedList])
+  const setCollapsed = (next: Set<string>) => {
+    const arr = [...next]
+    if (collapsedSpanIds === undefined) setOwnCollapsed(arr)
+    onCollapsedSpanIdsChange?.(arr)
+  }
+  const toggle = (id: string, fold?: boolean) => {
+    const next = new Set(collapsed)
+    if (fold ?? !next.has(id)) next.add(id)
+    else next.delete(id)
+    setCollapsed(next)
+  }
+  const parents = ordered.filter((o) => (tree.get(o.span.spanId)?.descendants ?? 0) > 0).map((o) => o.span.spanId)
+  const allCollapsed = parents.length > 0 && parents.every((id) => collapsed.has(id))
+  const anyCollapsed = parents.some((id) => collapsed.has(id))
+
+  // A span under a folded ancestor isn't drawn: skip the rest of its subtree.
+  const visible = useMemo(() => {
+    const out: typeof ordered = []
+    let hideBelow: number | null = null
+    for (const o of ordered) {
+      if (hideBelow !== null && o.depth > hideBelow) continue
+      hideBelow = collapsed.has(o.span.spanId) && (tree.get(o.span.spanId)?.descendants ?? 0) > 0 ? o.depth : null
+      out.push(o)
+    }
+    return out
+  }, [ordered, collapsed, tree])
+
+  // Selecting a span from outside the tree (a log line) unfolds its ancestors, so the row it
+  // highlights is on screen.
+  const selectAndReveal = (id: string | null) => {
+    if (id) {
+      const next = new Set(collapsed)
+      let changed = false
+      for (let p = tree.get(id)?.parentId ?? null; p; p = tree.get(p)?.parentId ?? null) {
+        if (next.delete(p)) changed = true
+      }
+      if (changed) setCollapsed(next)
+    }
+    setSelected(id)
+  }
+  const { t0, total } = useMemo(() => {
+    if (!spans.length) return { t0: 0, total: 0.001 }
+    let lo = Infinity
+    let hi = -Infinity
+    for (const s of spans) {
+      lo = Math.min(lo, s.startTimeMs)
+      hi = Math.max(hi, s.startTimeMs + s.durationMs)
+    }
+    return { t0: lo, total: Math.max(0.001, hi - lo) }
+  }, [spans])
+  const selectedSpan = ordered.find((o) => o.span.spanId === selected)?.span ?? null
+  const spanIds = useMemo(() => new Set(spans.map((s) => s.spanId)), [spans])
+
+  const nameCol = fullWidth ? "minmax(16rem,26rem)" : "minmax(11rem,18rem)"
+  const gridCols = `${nameCol} 1fr 5rem`
+  const ticks = [0, 0.25, 0.5, 0.75, 1]
+  // Continuous vertical gridlines behind every bar row (quarters of the timeline).
+  const gridBg =
+    "repeating-linear-gradient(to right, color-mix(in oklch, var(--border) 60%, transparent) 0 1px, transparent 1px 25%)"
+
+  return (
+    <div className={cn("space-y-3", className)}>
+      <div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-xs text-muted-foreground">
+        {traceId && (
+          <>
+            <span className="font-mono text-[11px]">{traceId}</span>
+            <span>·</span>
+          </>
+        )}
+        <span>
+          {spans.length} span{spans.length !== 1 ? "s" : ""}
+        </span>
+        <span>·</span>
+        <span className="font-mono tabular-nums text-foreground">{formatLatency(spans.length ? total : 0)}</span>
+        {parents.length > 0 && (
+          <span className="ml-auto flex items-center gap-1">
+            <button
+              type="button"
+              disabled={allCollapsed}
+              onClick={() => setCollapsed(new Set(parents))}
+              className="rounded-md px-1.5 py-0.5 transition-colors hover:bg-muted hover:text-foreground disabled:pointer-events-none disabled:opacity-40"
+            >
+              Collapse all
+            </button>
+            <span aria-hidden>·</span>
+            <button
+              type="button"
+              disabled={!anyCollapsed}
+              onClick={() => setCollapsed(new Set())}
+              className="rounded-md px-1.5 py-0.5 transition-colors hover:bg-muted hover:text-foreground disabled:pointer-events-none disabled:opacity-40"
+            >
+              Expand all
+            </button>
+          </span>
+        )}
+      </div>
+
+      <div className="overflow-hidden rounded-xl border border-border bg-card">
+        {/* Time-axis ruler */}
+        <div
+          className="sticky top-0 z-10 grid items-center border-b border-border bg-muted/40 backdrop-blur"
+          style={{ gridTemplateColumns: gridCols }}
+        >
+          <div className="px-3 py-1.5 text-[10px] font-medium uppercase tracking-wide text-muted-foreground">Span</div>
+          <div className="relative h-6">
+            {ticks.map((f) => (
+              <span
+                key={f}
+                className={cn(
+                  "absolute top-1/2 -translate-y-1/2 font-mono text-[9.5px] tabular-nums text-muted-foreground/80",
+                  f === 0 ? "left-1" : f === 1 ? "right-1" : "-translate-x-1/2"
+                )}
+                style={f !== 0 && f !== 1 ? { left: `${f * 100}%` } : undefined}
+              >
+                {formatLatency(f * total)}
+              </span>
+            ))}
+          </div>
+          <div className="px-3 py-1.5 text-right text-[10px] font-medium uppercase tracking-wide text-muted-foreground">
+            Duration
+          </div>
+        </div>
+
+        {/* Span rows */}
+        <div className="max-h-[calc(100vh-16rem)] overflow-y-auto">
+          {ordered.length === 0 && (
+            <p className="px-3 py-6 text-center text-xs text-muted-foreground">No spans in this trace.</p>
+          )}
+          {visible.map(({ span: s, depth }) => {
+            const left = ((s.startTimeMs - t0) / total) * 100
+            const width = Math.max(0.5, (s.durationMs / total) * 100)
+            const isSel = selected === s.spanId
+            const color = colorOf(s)
+            const info = tree.get(s.spanId)
+            const foldable = (info?.descendants ?? 0) > 0
+            const isFolded = foldable && collapsed.has(s.spanId)
+            // The row is a div, not a button: it holds the fold chevron, and a button can't hold a
+            // button. Keyboard parity by hand — Enter/Space select, ←/→ fold/unfold.
+            const onKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
+              if (e.target !== e.currentTarget) return
+              if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault()
+                setSelected(isSel ? null : s.spanId)
+              } else if (foldable && e.key === "ArrowLeft" && !isFolded) {
+                e.preventDefault()
+                toggle(s.spanId, true)
+              } else if (foldable && e.key === "ArrowRight" && isFolded) {
+                e.preventDefault()
+                toggle(s.spanId, false)
+              }
+            }
+            return (
+              <div
+                key={s.spanId}
+                role="button"
+                tabIndex={0}
+                onClick={() => setSelected(isSel ? null : s.spanId)}
+                onKeyDown={onKeyDown}
+                aria-pressed={isSel}
+                aria-expanded={foldable ? !isFolded : undefined}
+                className={cn(
+                  "grid w-full cursor-pointer items-center border-b border-border/50 text-left outline-none transition-colors last:border-0 hover:bg-muted/40 focus-visible:bg-muted/60",
+                  isSel && "bg-run/5 hover:bg-run/10"
+                )}
+                style={{ gridTemplateColumns: gridCols }}
+              >
+                {/* Fold chevron + depth guides + name */}
+                <span className="flex min-w-0 items-center py-2 pl-1.5 pr-2">
+                  <span className="flex shrink-0 items-center" aria-hidden>
+                    {Array.from({ length: depth }).map((_, i) => (
+                      <span key={i} className="ml-1 mr-1 h-4 w-px bg-border/70" />
+                    ))}
+                  </span>
+                  {foldable ? (
+                    <button
+                      type="button"
+                      tabIndex={-1}
+                      onClick={(e) => {
+                        e.stopPropagation()
+                        toggle(s.spanId)
+                      }}
+                      aria-label={isFolded ? `Expand ${s.name}` : `Collapse ${s.name}`}
+                      className="mr-0.5 flex h-5 w-5 shrink-0 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+                    >
+                      <ChevronRightIcon className={cn("h-3.5 w-3.5 transition-transform", !isFolded && "rotate-90")} />
+                    </button>
+                  ) : (
+                    <span className="mr-0.5 w-5 shrink-0" aria-hidden />
+                  )}
+                  {s.error && <span className="mr-1.5 h-1.5 w-1.5 shrink-0 rounded-full bg-destructive" />}
+                  <span className="mr-2 h-2.5 w-1 shrink-0 rounded-sm" style={{ background: color }} aria-hidden />
+                  <span className={cn("truncate font-mono text-[12px]", isSel && "text-foreground")}>{s.name}</span>
+                  {isFolded && (
+                    <span
+                      className={cn(
+                        "ml-1.5 shrink-0 rounded-full border px-1.5 font-mono text-[10px] tabular-nums",
+                        info!.descendantError
+                          ? "border-destructive/30 bg-destructive/10 text-destructive"
+                          : "border-border bg-muted text-muted-foreground"
+                      )}
+                      title={`${info!.descendants} span${info!.descendants !== 1 ? "s" : ""} hidden${info!.descendantError ? ", including an error" : ""}`}
+                    >
+                      +{info!.descendants}
+                    </span>
+                  )}
+                </span>
+
+                {/* Timeline bar */}
+                <span className="relative mx-2 hidden h-6 items-center sm:flex" style={{ backgroundImage: gridBg }}>
+                  <span
+                    className="absolute h-2.5 min-w-[2px] rounded-[3px]"
+                    style={{ left: `${left}%`, width: `${width}%`, background: color }}
+                    title={`${formatLatency(s.durationMs)} @ +${formatLatency(s.startTimeMs - t0)}`}
+                  />
+                </span>
+
+                {/* Duration */}
+                <span className="px-3 py-2 text-right font-mono text-[11px] tabular-nums text-muted-foreground">
+                  {formatLatency(s.durationMs)}
+                </span>
+              </div>
+            )
+          })}
+        </div>
+      </div>
+
+      {/* Selected span detail */}
+      {selectedSpan && (
+        <SpanDetail span={selectedSpan} offsetMs={selectedSpan.startTimeMs - t0} color={colorOf(selectedSpan)} />
+      )}
+
+      {legend && (
+        <p className="text-center text-xs text-muted-foreground/70">
+          {LEGEND.map(([label, color], i) => (
+            <span key={label}>
+              {i > 0 && "  ·  "}
+              <span className="inline-flex items-center gap-1">
+                <span className="h-2 w-2 rounded-sm" style={{ background: color }} /> {label}
+              </span>
+            </span>
+          ))}
+          {parents.length > 0 ? "  ·  click a span for details, the chevron to fold it" : "  ·  click a span for details"}
+        </p>
+      )}
+
+      {(logs !== undefined || logsStatus) && (
+        <div className="space-y-2">
+          <div className="flex items-baseline justify-between gap-2">
+            <h3 className="text-sm font-medium">Logs</h3>
+            <span className="text-xs text-muted-foreground">
+              {logsStatus === "loading"
+                ? "loading…"
+                : logsStatus === "error"
+                  ? "unavailable"
+                  : `${logs?.length ?? 0} line${logs?.length === 1 ? "" : "s"} with this trace id`}
+            </span>
+          </div>
+          {!logsStatus && logs?.length === 0 ? (
+            <p className="rounded-lg border border-dashed px-3 py-4 text-center text-xs text-muted-foreground">
+              No log line carries this trace id — only lines written inside a span (with the trace context active) are
+              linked.
+            </p>
+          ) : (
+            logs &&
+            logs.length > 0 && (
+              <LogLines
+                lines={logs}
+                origin={t0}
+                spanIds={spanIds}
+                selectedSpanId={selected}
+                onSelectSpan={selectAndReveal}
+                className="max-h-80"
+              />
+            )
+          )}
+        </div>
+      )}
+    </div>
+  )
+}
+
+function SpanDetail({ span, offsetMs, color }: { span: TraceSpan; offsetMs: number; color: string }) {
+  const attrs = Object.entries(span.attributes ?? {})
+  return (
+    <div className="rounded-xl border border-border bg-card p-4">
+      <div className="mb-3 flex flex-wrap items-center gap-2">
+        <span className="h-3 w-1.5 rounded-sm" style={{ background: color }} aria-hidden />
+        <span className="font-mono text-sm">{span.name}</span>
+        {span.error && (
+          <span className="rounded-full border border-destructive/30 bg-destructive/10 px-2 py-0.5 text-[10px] font-medium text-destructive">
+            error
+          </span>
+        )}
+        <span className="ml-auto font-mono text-xs tabular-nums text-muted-foreground">
+          {formatLatency(span.durationMs)} · +{formatLatency(offsetMs)}
+        </span>
+      </div>
+      <div className="mb-3 flex flex-wrap gap-x-4 gap-y-1 text-xs text-muted-foreground">
+        <span>
+          service <span className="font-mono text-foreground">{span.service || "—"}</span>
+        </span>
+        {span.kind && (
+          <span>
+            kind <span className="font-mono text-foreground">{span.kind}</span>
+          </span>
+        )}
+      </div>
+      {attrs.length > 0 ? (
+        <div className="grid gap-x-4 gap-y-1" style={{ gridTemplateColumns: "minmax(8rem,auto) 1fr" }}>
+          {attrs.map(([k, v]) => (
+            <div key={k} className="contents">
+              <span className="truncate font-mono text-[11px] text-muted-foreground/80">{k}</span>
+              <span className="break-all font-mono text-[11px] text-foreground">{v}</span>
+            </div>
+          ))}
+        </div>
+      ) : (
+        <p className="text-xs text-muted-foreground">No attributes.</p>
+      )}
+    </div>
+  )
+}
+
+/** Placeholder rows with the waterfall's geometry, while the app fetches the spans. */
+export function SpanWaterfallSkeleton({ rows = 10, className }: { rows?: number; className?: string }) {
+  return (
+    <div className={cn("space-y-2", className)}>
+      {Array.from({ length: rows }).map((_, i) => (
+        <div key={i} className="h-8 animate-pulse rounded-md border border-border bg-muted/40" />
+      ))}
+    </div>
+  )
+}