@photon-ai/pho-ui 2.16.0 → 2.17.0

package/dist/src/components/trace/decorations.d.ts

@@ -0,0 +1,32 @@
+import { Icon } from '@tabler/icons-react';
+export interface SpanPill {
+    /** The attribute the value came from — the tooltip and the label for readers. */
+    label: string;
+    value: string;
+    /** The value is a failure (a 5xx status). */
+    error?: boolean;
+}
+export interface SpanDecorationIcon {
+    icon: Icon;
+    /** What the icon means, for readers and the tooltip; absent for a plain namespace icon. */
+    label?: string;
+}
+export type GenAIKind = "agent" | "llm" | "tool" | "retrieval" | "generic";
+type Attributes = Readonly<Record<string, unknown>> | undefined;
+export declare const GEN_AI_KINDS: Record<GenAIKind, {
+    icon: Icon;
+    label: string;
+}>;
+/** An attribute's value as text; objects as JSON, nothing for null. */
+export declare function attributeText(value: unknown): string;
+/** The first of `keys` with a non-empty value, as text. */
+export declare function attribute(attributes: Attributes, keys: readonly string[]): string | null;
+/** The GenAI kind of a span, from `gen_ai.operation.name`; `generic` for any other `gen_ai.*`. */
+export declare function genAIKind(attributes: Attributes): GenAIKind | null;
+/** The one icon for a span, GenAI kind first, then the first namespace with one. */
+export declare function spanDecorationIcon(attributes: Attributes): SpanDecorationIcon | null;
+/** The pills for a span, in registry order. */
+export declare function spanPills(attributes: Attributes): SpanPill[];
+/** `peer.service` — the service a client span called, when it named one. */
+export declare function peerService(attributes: Attributes): string | null;
+export {};

package/dist/src/components/trace/index.d.ts

@@ -1,2 +1,5 @@
-export { Trace, type TraceRootProps, type TraceLogsProps, type TraceLog, type TraceLogLevel, } from './trace';
-export { layoutTrace, niceStep, formatDuration, formatTick, type TraceSpan, type TraceRow, type TraceLayout, } from './layout';
+export { Trace, traceBulletInset, footerTotals, type TraceWaterfallProps, type TraceWaterfallShortcuts, type WaterfallFooterProps, type TraceLogsProps, type TraceLog, type TraceLogLevel, } from './trace';
+export { SpanPrimitive, useSpan, useSpanTree, type SpanTreeContextValue, type SpanProviderProps, type SpanChildrenProps, type SpanRootProps, type SpanIndentProps, type SpanCollapseToggleProps, type SpanStatusIndicatorProps, type SpanTypeBadgeProps, type SpanNameProps, type SpanTimelineProps, type SpanTimelineBarProps, } from './span-primitive';
+export { deriveSpanTree, visibleSpans, buildSpanTree, ancestorIds, collapseAllIds, collapseOneLevel, expandOneLevel, allCollapsed, traceRange, clampView, viewToRange, zoomView, panView, viewFraction, isFullView, spanTimelineBarVars, filterSpans, FULL_VIEW, MIN_VIEW_WIDTH, type SpanData, type SpanStatus, type SpanKind, type SpanItemState, type SpanTree, type SpanTimelineRange, type SpanView, } from './span-tree';
+export { spanDecorationIcon, spanPills, genAIKind, peerService, attribute, attributeText, GEN_AI_KINDS, type SpanPill, type SpanDecorationIcon, type GenAIKind, } from './decorations';
+export { normalizeSpans, spanDuration, barGeometry, axisTicks, niceStep, formatDuration, formatTick, labeledTicks, type AxisTick, type TraceWaterfallSpan, type TraceSpanStatus, type TraceSpanKind, type TraceRange, } from './layout';

package/dist/src/components/trace/layout.d.ts

@@ -1,48 +1,76 @@
+import { SpanData, SpanKind, SpanStatus, SpanTimelineRange } from './span-tree';
+export type TraceSpanStatus = SpanStatus;
+export type TraceSpanKind = SpanKind;
+export type TraceRange = SpanTimelineRange;
 /**
- * The waterfall's arithmetic, apart from the drawing: spans in, rows out
- * — each with its depth and its bar's place along the trace's length —
- * plus the tick marks for the time axis.
+ * A span as the waterfall takes it — `SpanData` with its derivable
+ * fields optional. A `SpanData` passes through unchanged.
  */
-export interface TraceSpan {
+export interface TraceWaterfallSpan {
     id: string;
     /** The span this one runs inside. Absent (or unknown) means a root. */
-    parentId?: string | null;
+    parentSpanId?: string | null;
     name: string;
+    /** The category — http, db, llm, tool. Shows after the service as a hint. */
+    type?: string;
+    /** `completed` with an end, `running` without, unless told otherwise. */
+    status?: TraceSpanStatus;
+    /** OpenTelemetry kind. A folded `client` names its `server` child. */
+    kind?: TraceSpanKind;
     /** Start, in ms, on any shared clock — only the differences matter. */
-    startMs: number;
-    durationMs: number;
-    status?: "ok" | "error" | "unset";
+    startedAt: number;
+    /** End, in ms; `null` (or absent) while the span still runs. */
+    endedAt?: number | null;
+    /** The measured duration; `endedAt - startedAt` when absent. */
+    latencyMs?: number | null;
     /** A hint after the name — the service, the host. */
     service?: string;
-    /** A hint after the service — client, server, db. */
-    kind?: string;
+    /**
+     * Flat OpenTelemetry attributes. `http.response.status_code`,
+     * `db.system`, `gen_ai.request.model` become pills; the namespace
+     * picks the icon; `peer.service` names an uninstrumented callee; all
+     * of them are searchable.
+     */
+    attributes?: Readonly<Record<string, unknown>>;
 }
-export interface TraceRow {
-    span: TraceSpan;
-    depth: number;
-    /** The bar's start, as a fraction of the trace's length. */
+/** Fill in what the tree requires and the input left implicit. */
+export declare function normalizeSpans(spans: readonly TraceWaterfallSpan[]): SpanData[];
+/** How long a span took — or has taken so far, given `now`. */
+export declare function spanDuration(span: Pick<SpanData, "startedAt" | "endedAt" | "latencyMs">, now?: number): number | null;
+/**
+ * A bar's start and length as fractions of the range — the same numbers
+ * `SpanPrimitive.TimelineBar` draws with, for placing the label beside it.
+ */
+export declare function barGeometry(span: Pick<SpanData, "startedAt" | "endedAt">, range: TraceRange, now?: number): {
     left: number;
-    /** The bar's length, as a fraction of the trace's length. */
     width: number;
-    children: string[];
-    /** Every span beneath this one, at any depth. */
-    descendants: number;
-}
-export interface TraceLayout {
-    /** Every span, root first, each parent before its children. */
-    rows: TraceRow[];
-    startMs: number;
-    endMs: number;
-    durationMs: number;
-    /** Tick marks along the axis, in ms from the start. */
-    ticks: number[];
-}
+};
 /** A tick step from the 1 / 2 / 5 ladder so the axis has at most `max` ticks. */
 export declare function niceStep(durationMs: number, max?: number): number;
-export declare function layoutTrace(spans: readonly TraceSpan[]): TraceLayout;
+export interface AxisTick {
+    /** Where along the track, as a fraction. */
+    at: number;
+    /** The time it marks, in ms from the trace's start. */
+    ms: number;
+}
+/**
+ * Tick marks for the window `[startMs, endMs]` of a trace, in ms from
+ * the trace's start: round multiples of a nice step, so a zoomed axis
+ * still reads `20 ms, 25 ms, 30 ms`. `[{ at: 0, ms: startMs }]` for a
+ * window with no length.
+ */
+export declare function axisTicks(startMs: number, endMs: number): AxisTick[];
 /** "0.42 ms", "59.2 ms", "1.25 s" — the precision follows the size. */
 export declare function formatDuration(ms: number): string;
 /** An axis tick's label: whole numbers where the step allows, "2 s" past a second. */
 export declare function formatTick(ms: number): string;
+/**
+ * Which tick marks get a label at this track width. Marks themselves
+ * always draw; a label hides when it would overlap the previous one.
+ * The last tick is treated as right-aligned so it never runs past the
+ * track's edge — at a narrow axis that often means dropping the label
+ * before it (`40 ms` next to `50 ms` on a ~335px track).
+ */
+export declare function labeledTicks(ticks: readonly AxisTick[], trackPx: number): number[];
 /** A fraction as a CSS percentage, rounded so floats never leak into styles. */
 export declare function percent(fraction: number): string;

package/dist/src/components/trace/span-primitive.d.ts

@@ -0,0 +1,168 @@
+import { ReactNode } from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import { SpanData, SpanItemState, SpanTimelineRange, SpanView } from './span-tree';
+/**
+ * SpanPrimitive — headless parts for a tree of spans: the pieces a
+ * waterfall, a timeline, or a run inspector is composed from, with no
+ * styling of their own.
+ *
+ * Modelled on `@assistant-ui/react-o11y`'s `SpanPrimitive` (same data
+ * attributes, same CSS variables, same part names) so a host that knows
+ * that shape can style either — but with no store behind it: the tree is
+ * derived once per change and shared through plain context, folding is
+ * controllable, and every part takes Base UI's `render` prop in place of
+ * Radix's `asChild`. The tree's edge cases and the fold, search, and
+ * zoom arithmetic come from Jaeger UI's trace view; see `span-tree.ts`.
+ *
+ * - `Provider` takes the flat `SpanData[]`, derives the tree (depth,
+ *   order, descendants and their errors, orphans, repaired times) and
+ *   the time range, and owns the fold, the search matches, and the zoom
+ *   window — each uncontrolled by default, controlled with a prop.
+ * - `Children` renders each visible span in turn, root first, parents
+ *   before their children, siblings by start; a folded parent hides its
+ *   subtree. Inside it, `useSpan()` is the current span and
+ *   `useSpanTree()` the whole tree with its actions.
+ * - `Root`, `Indent`, `CollapseToggle`, `StatusIndicator`, `TypeBadge`,
+ *   `Name` are the row's parts; `Timeline` supplies the (zoomed) range
+ *   as CSS variables and `TimelineBar` places the current span along it.
+ */
+export interface SpanTreeContextValue {
+    /** The visible rows, in reading order. */
+    spans: readonly SpanItemState[];
+    /** Every span, folded or not, in reading order. */
+    all: readonly SpanItemState[];
+    byId: ReadonlyMap<string, SpanItemState>;
+    /** Spans whose parent the trace does not have. */
+    orphans: number;
+    /** Spans whose start or end had to be repaired. */
+    repaired: number;
+    /** The whole trace. */
+    range: SpanTimelineRange;
+    /** The zoom window, as fractions of the trace. */
+    view: SpanView;
+    /** The part of the range the window shows. */
+    viewRange: SpanTimelineRange;
+    zoomed: boolean;
+    now: number | undefined;
+    collapsed: ReadonlySet<string>;
+    toggle: (id: string) => void;
+    setCollapsed: (ids: readonly string[]) => void;
+    expandAll: () => void;
+    collapseAll: () => void;
+    /** Open the shallowest folded parent on every branch. */
+    expandOne: () => void;
+    /** Fold the deepest open parent on every branch. */
+    collapseOne: () => void;
+    canExpand: boolean;
+    canCollapse: boolean;
+    query: string;
+    /** The spans the query names; `null` with no query. */
+    matches: ReadonlySet<string> | null;
+    setView: (view: SpanView) => void;
+    /** Scale the window; below 1 zooms in. `anchor` is a fraction of the window. */
+    zoom: (factor: number, anchor?: number) => void;
+    /** Slide the window by a fraction of its own width. */
+    pan: (delta: number) => void;
+    resetView: () => void;
+}
+/** The whole tree: visible spans, the ranges, and the fold / search / zoom actions. */
+export declare function useSpanTree(): SpanTreeContextValue;
+/** The span this part belongs to — set by `SpanPrimitive.Children`. */
+export declare function useSpan(): SpanItemState;
+export interface SpanProviderProps {
+    spans: readonly SpanData[];
+    /** Spans folded at first (uncontrolled). */
+    defaultCollapsed?: readonly string[];
+    /** Spans folded (controlled). */
+    collapsed?: readonly string[];
+    onCollapsedChange?: (ids: string[]) => void;
+    /** The current time on the spans' clock — where a running span ends. */
+    now?: number;
+    /**
+     * A search over the spans (see `filterSpans`). Matching spans are
+     * `matches`; their folded ancestors open so every match is in view.
+     */
+    query?: string;
+    /** Leave folded ancestors of matches folded. */
+    keepFoldsOnMatch?: boolean;
+    /** The zoom window at first (uncontrolled). */
+    defaultView?: SpanView;
+    /** The zoom window (controlled). */
+    view?: SpanView;
+    onViewChange?: (view: SpanView) => void;
+    children: ReactNode;
+}
+declare function Provider({ spans, defaultCollapsed, collapsed: collapsedProp, onCollapsedChange, now, query, keepFoldsOnMatch, defaultView, view: viewProp, onViewChange, children, }: SpanProviderProps): import("react").JSX.Element;
+export interface SpanChildrenProps {
+    /** Rendered once per visible span; `useSpan()` inside reads that span. */
+    children: (span: SpanItemState) => ReactNode;
+}
+declare function Children({ children }: SpanChildrenProps): import("react").JSX.Element[];
+export type SpanRootProps = useRender.ComponentProps<"div">;
+/**
+ * The row: a div carrying the span's state as data attributes —
+ * `data-span-id`, `-status`, `-type`, `-depth`, `-kind`, `data-collapsed`,
+ * `data-match` while the search names it, `data-orphan` for a span
+ * whose parent the trace lacks.
+ */
+declare function Root({ render, ref, ...props }: SpanRootProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
+export type SpanIndentProps = useRender.ComponentProps<"div"> & {
+    /** Padding at depth 0, in px. @default 8 */
+    baseIndent?: number;
+    /** Padding added per level, in px. @default 12 */
+    indentPerLevel?: number;
+};
+/** A div padded on the left for the span's depth. */
+declare function Indent({ render, ref, baseIndent, indentPerLevel, style, ...props }: SpanIndentProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
+export type SpanCollapseToggleProps = useRender.ComponentProps<"button">;
+/** The fold button; renders nothing for a span with no children. */
+declare function CollapseToggle({ render, ref, onClick, ...props }: SpanCollapseToggleProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | null;
+export type SpanStatusIndicatorProps = useRender.ComponentProps<"span">;
+/**
+ * A span carrying `data-span-status`, for a dot or an icon — and
+ * `data-descendant-errors` while a fold hides failed spans beneath it.
+ */
+declare function StatusIndicator({ render, ref, ...props }: SpanStatusIndicatorProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
+export type SpanTypeBadgeProps = useRender.ComponentProps<"span">;
+/** The span's type as text, unless given children. */
+declare function TypeBadge({ render, ref, children, ...props }: SpanTypeBadgeProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
+export type SpanNameProps = useRender.ComponentProps<"span">;
+/** The span's name as text, unless given children. */
+declare function Name({ render, ref, children, ...props }: SpanNameProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
+export type SpanTimelineProps = useRender.ComponentProps<"div"> & {
+    /** The range to draw against. @default the tree's zoom window */
+    timeRange?: SpanTimelineRange;
+    /** Room after the end, as a fraction of the range. @default 0 */
+    paddingEnd?: number;
+};
+/**
+ * The track every bar inside it is placed along. Exposes the range as
+ * `--span-timeline-min-ms` / `-max-ms` / `-range-ms`.
+ */
+declare function Timeline({ render, ref, timeRange, paddingEnd, style, ...props }: SpanTimelineProps): import("react").JSX.Element;
+export type SpanTimelineBarProps = useRender.ComponentProps<"div"> & {
+    /** Where a running span ends. @default the tree's `now`, else the range's end */
+    now?: number;
+    /** @default the nearest Timeline's range */
+    timeRange?: SpanTimelineRange;
+};
+/**
+ * The current span's bar, positioned absolutely from
+ * `--span-timeline-left` and sized from `--span-timeline-width` (never
+ * under `--span-timeline-min-width`, when the host sets one). Carries
+ * `data-clipped-start` / `data-clipped-end` when the range cuts it off.
+ */
+declare function TimelineBar({ render, ref, now, timeRange, style, ...props }: SpanTimelineBarProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
+export declare const SpanPrimitive: {
+    Provider: typeof Provider;
+    Children: typeof Children;
+    Root: typeof Root;
+    Indent: typeof Indent;
+    CollapseToggle: typeof CollapseToggle;
+    StatusIndicator: typeof StatusIndicator;
+    TypeBadge: typeof TypeBadge;
+    Name: typeof Name;
+    Timeline: typeof Timeline;
+    TimelineBar: typeof TimelineBar;
+};
+export {};

package/dist/src/components/trace/span-tree.d.ts

@@ -0,0 +1,148 @@
+/**
+ * The span tree, apart from React: the shape a waterfall needs from a flat
+ * list of spans, and the arithmetic on it. Everything here is pure and
+ * runs the same on the server.
+ *
+ * The edge cases follow Jaeger UI's trace model (Apache-2.0, reimplemented
+ * from its behaviour, not its code): a parent the trace does not have makes
+ * an orphan, not a crash; a cycle is broken where it closes; a span with no
+ * usable start inherits its parent's instead of dragging the axis to the
+ * epoch; an error under a folded parent stays countable; a client span
+ * remembers its server child so a fold can still name the peer.
+ */
+export type SpanStatus = "running" | "completed" | "failed" | "skipped";
+/** OpenTelemetry's span kinds, lower-cased. */
+export type SpanKind = "client" | "server" | "producer" | "consumer" | "internal";
+export interface SpanData {
+    id: string;
+    /** The span this one runs inside; `null` for a root. */
+    parentSpanId: string | null;
+    name: string;
+    /** The category — http, db, llm, tool. */
+    type: string;
+    status: SpanStatus;
+    /** Start, in ms, on any shared clock — only the differences matter. */
+    startedAt: number;
+    /** End, in ms; `null` while the span still runs. */
+    endedAt: number | null;
+    /** The measured duration, when the tracer reports one. */
+    latencyMs: number | null;
+    /** OpenTelemetry kind, when known — a `client` fold can name its server. */
+    kind?: SpanKind;
+    /** The service (resource) the span ran in. */
+    service?: string;
+    /** Flat OpenTelemetry attributes — `http.response.status_code`, `db.system`. */
+    attributes?: Readonly<Record<string, unknown>>;
+}
+/** A span as the tree knows it: its data plus its place in the tree. */
+export interface SpanItemState extends SpanData {
+    depth: number;
+    hasChildren: boolean;
+    isCollapsed: boolean;
+    /** Every span beneath this one, at any depth, folded or not. */
+    descendants: number;
+    /** How many of those failed. */
+    descendantErrors: number;
+    /** Named a parent the trace does not have (or one in a cycle); shown as a root. */
+    orphan: boolean;
+    /** Its start or end was missing or not a number and was repaired. */
+    repaired: boolean;
+    /** For a `client` span: the first direct child that is a `server` span. */
+    serverChildId: string | null;
+}
+export interface SpanTimelineRange {
+    min: number;
+    max: number;
+}
+/** A zoom window, as fractions of the trace's range. `[0, 1]` is all of it. */
+export type SpanView = readonly [start: number, end: number];
+export declare const FULL_VIEW: SpanView;
+/** The narrowest a zoom window goes, as a fraction of the trace. */
+export declare const MIN_VIEW_WIDTH = 0.001;
+export interface SpanTree {
+    /** Every span, root first, each parent before its children, siblings by start. */
+    spans: readonly SpanItemState[];
+    byId: ReadonlyMap<string, SpanItemState>;
+    /** Spans whose parent the trace does not have. */
+    orphans: number;
+    /** Spans whose start or end had to be repaired. */
+    repaired: number;
+}
+/**
+ * Derive the tree once from the flat list: depth, order, descendants and
+ * their errors, orphans, repaired times, and each client's server child.
+ * Nothing here depends on folding; see `visibleSpans` for that.
+ */
+export declare function deriveSpanTree(spans: readonly SpanData[]): SpanTree;
+/**
+ * The visible rows: the tree in reading order with every folded parent's
+ * subtree left out. Untouched items keep their identity; a folded parent
+ * is a copy with `isCollapsed` set.
+ */
+export declare function visibleSpans(tree: SpanTree, collapsed: ReadonlySet<string>): SpanItemState[];
+/** Derive and fold in one step — `visibleSpans(deriveSpanTree(spans), collapsed)`. */
+export declare function buildSpanTree(spans: readonly SpanData[], collapsed?: ReadonlySet<string>): SpanItemState[];
+/** The ids above a span, nearest parent first. */
+export declare function ancestorIds(byId: ReadonlyMap<string, Pick<SpanItemState, "parentSpanId">>, id: string): string[];
+/** Every parent — the fold state after "collapse all". */
+export declare function collapseAllIds(spans: readonly SpanItemState[]): string[];
+/** True when every parent is already folded, so "collapse" has nothing to do. */
+export declare function allCollapsed(spans: readonly SpanItemState[], collapsed: ReadonlySet<string>): boolean;
+/**
+ * Fold one level: the deepest open parent on every branch closes. Pressed
+ * again, the level above; and so on up to the roots.
+ */
+export declare function collapseOneLevel(spans: readonly SpanItemState[], collapsed: ReadonlySet<string>): string[];
+/**
+ * Open one level: the shallowest folded parent on every branch opens.
+ * The inverse of `collapseOneLevel`.
+ */
+export declare function expandOneLevel(spans: readonly SpanItemState[], collapsed: ReadonlySet<string>): string[];
+/**
+ * The trace runs from the earliest start to the latest end. A running
+ * span ends at `now` when there is one; otherwise it counts only its
+ * start, and its bar stretches to whatever the rest of the trace spans.
+ */
+export declare function traceRange(spans: readonly Pick<SpanData, "startedAt" | "endedAt">[], now?: number): SpanTimelineRange;
+/** A zoom window made sane: ordered, inside `[0, 1]`, never thinner than the minimum. */
+export declare function clampView(view: SpanView): SpanView;
+/** The window's part of the range, in the range's units. */
+export declare function viewToRange(range: SpanTimelineRange, view: SpanView): SpanTimelineRange;
+/**
+ * Scale the window by `factor` (below 1 zooms in) around `anchor`, a
+ * fraction of the *window*; the point under the anchor stays put.
+ */
+export declare function zoomView(view: SpanView, factor: number, anchor?: number): SpanView;
+/** Slide the window by `delta` of its own width; it stops at either end. */
+export declare function panView(view: SpanView, delta: number): SpanView;
+/** Map a window-relative fraction (a pointer on the axis) to a trace fraction. */
+export declare function viewFraction(view: SpanView, at: number): number;
+export declare function isFullView(view: SpanView): boolean;
+/**
+ * Where a span's bar sits along a range, in percent. A running span ends
+ * at `now`, or at the range's end without one; everything clamps to the
+ * range so a bar never leaves the track, and the clipped flags say when
+ * it did.
+ */
+export declare function spanTimelineBarVars({ startedAt, endedAt, timeRange, now, }: {
+    startedAt: number;
+    endedAt: number | null;
+    timeRange: SpanTimelineRange;
+    now?: number;
+}): {
+    leftPercent: number;
+    endPercent: number;
+    widthPercent: number;
+    durationMs: number;
+    effectiveEnd: number;
+    clippedStart: boolean;
+    clippedEnd: boolean;
+};
+/**
+ * Which spans a query names. Space-separated terms, any of which may
+ * match; `"a phrase"` keeps its spaces; `-key` leaves an attribute out
+ * of the matching. A term matches the name, the service, the type, the
+ * kind, the exact id, or an attribute's key, value, or `key=value`.
+ * `null` for a blank query.
+ */
+export declare function filterSpans(query: string | null | undefined, spans: readonly SpanData[]): Set<string> | null;

package/dist/src/components/trace/trace.d.ts

@@ -1,21 +1,107 @@
 import { ComponentProps, ReactNode, Ref } from 'react';
-import { TraceSpan } from './layout';
-export interface TraceRootProps extends Omit<ComponentProps<"div">, "children" | "onSelect" | "title"> {
-    spans: readonly TraceSpan[];
+import { SpanView } from './span-tree';
+import { TraceWaterfallSpan } from './layout';
+/**
+ * Left edge of a row's bullet, in px, from the card. The detail panel
+ * uses this so its content starts under that dot at any depth.
+ */
+export declare function traceBulletInset(depth: number): string;
+export type TraceWaterfallShortcuts = "focus" | "global" | false;
+export interface TraceWaterfallProps extends Omit<ComponentProps<"section">, "children" | "onSelect" | "title"> {
+    spans: readonly TraceWaterfallSpan[];
+    /**
+     * The current time on the spans' clock, for running spans: their bars
+     * and durations grow to it. Omit and the waterfall ticks on its own
+     * while any span runs; pass it to drive the redraw yourself.
+     */
+    now?: number;
     /** The span whose details are open — it keeps the wash. */
     selectedId?: string | null;
-    /** Rows select on click when given. */
-    onSelect?: (id: string) => void;
+    /**
+     * Rows select on click when given. A second click on the selected
+     * row, or Escape, passes `null` so the host can close the detail.
+     */
+    onSelect?: (id: string | null) => void;
+    /**
+     * Facts for the selected span, drawn as a full-width panel under that
+     * row. Omit (or return `null`) for selection without a panel.
+     */
+    renderSpanDetail?: (span: TraceWaterfallSpan) => ReactNode;
     /** Spans folded at first (uncontrolled). */
     defaultCollapsed?: readonly string[];
     /** Spans folded (controlled). */
     collapsed?: readonly string[];
     onCollapsedChange?: (ids: string[]) => void;
-    /** A title row above the axis — "Waterfall". Omit for none. */
+    /**
+     * The fold controls in the header — one level and all, each way.
+     * Shown while the trace has a parent to fold. @default true
+     */
+    foldControls?: boolean;
+    /**
+     * A search box in a toolbar band above the header — `true`, or the
+     * placeholder it should show. Terms are space-separated and any may
+     * match; `"a phrase"` keeps its spaces; `-key` leaves an attribute out;
+     * `key=value` matches exactly. Matches take a wash and their folded
+     * ancestors open. Pass `query` with `onQueryChange` to own the text.
+     */
+    search?: boolean | string;
+    query?: string;
+    onQueryChange?: (query: string) => void;
+    /** The zoom window at first (uncontrolled), as fractions of the trace. */
+    defaultView?: SpanView;
+    /** The zoom window (controlled). */
+    view?: SpanView;
+    onViewChange?: (view: SpanView) => void;
+    /**
+     * Where the keyboard shortcuts listen: `"focus"` while focus is inside
+     * the card (click it, or tab to a row), `"global"` anywhere on the page
+     * outside a field, `false` for none. @default "focus"
+     */
+    shortcuts?: TraceWaterfallShortcuts;
+    /** The lead on the axis row — "Waterfall". Omit for none. */
     title?: ReactNode;
-    ref?: Ref<HTMLDivElement>;
+    /**
+     * Optional copy after `title` on the axis row. Totals live in the
+     * footer by default; pass a node here only to put something else
+     * beside the title.
+     */
+    summary?: ReactNode;
+    /**
+     * Wall-clock start of the trace, in ms. The footer prints
+     * `Started 12:59:07.206` when this is a readable time.
+     */
+    startedAt?: number;
+    /**
+     * The legend and totals under the rows. Default when there are
+     * spans; pass `null` to hide it, or a node (`<Trace.Waterfall.Footer />`)
+     * to replace it.
+     */
+    footer?: ReactNode;
+    ref?: Ref<HTMLElement>;
+}
+declare function Waterfall({ spans, now: nowProp, selectedId, onSelect, renderSpanDetail, defaultCollapsed, collapsed, onCollapsedChange, foldControls, search, query: queryProp, onQueryChange, defaultView, view, onViewChange, shortcuts, title, summary, startedAt, footer, className, ...props }: TraceWaterfallProps): import("react").JSX.Element;
+export declare function footerTotals({ spanCount, errorCount, orphanCount, durationMs, window, startedAt, }: {
+    spanCount: number;
+    errorCount: number;
+    orphanCount?: number;
+    durationMs: number;
+    /** The zoom window, in ms from the trace's start, when zoomed. */
+    window?: {
+        startMs: number;
+        endMs: number;
+    } | null;
+    startedAt?: number;
+}): string[];
+export interface WaterfallFooterProps extends ComponentProps<"div"> {
+    /** Wall-clock start; falls back to the waterfall's `startedAt`. */
+    startedAt?: number;
 }
-declare function Root({ spans, selectedId, onSelect, defaultCollapsed, collapsed: collapsedProp, onCollapsedChange, title, className, ...props }: TraceRootProps): import("react").JSX.Element;
+/**
+ * The waterfall's legend and totals. Renders inside `Trace.Waterfall`
+ * so it can read the spans; pass it as `footer` to keep the default
+ * chrome when replacing the slot.
+ */
+declare function WaterfallFooter({ startedAt: startedAtProp, className, ...props }: WaterfallFooterProps): import("react").JSX.Element;
 export type TraceLogLevel = "debug" | "info" | "warn" | "error";
 export interface TraceLog {
     id?: string;
@@ -29,7 +115,7 @@ export interface TraceLog {
 export interface TraceLogsProps extends Omit<ComponentProps<"section">, "children" | "title"> {
     logs?: readonly TraceLog[] | null;
     /** The spans, to name the one each line was written in. */
-    spans?: readonly TraceSpan[];
+    spans?: readonly Pick<TraceWaterfallSpan, "id" | "name">[];
     /** @default "Logs" */
     title?: ReactNode;
     ref?: Ref<HTMLElement>;
@@ -40,14 +126,10 @@ export interface TraceLogsProps extends Omit<ComponentProps<"section">, "childre
  * trace with no logs shows no empty block.
  */
 declare function Logs({ logs, spans, title, className, ...props }: TraceLogsProps): import("react").JSX.Element | null;
-/**
- * ```tsx
- * <Trace.Root spans={spans} selectedId={id} onSelect={setId} title="Waterfall" />
- * <Trace.Logs logs={logs} spans={spans} />
- * ```
- */
 export declare const Trace: {
-    Root: typeof Root;
+    Waterfall: typeof Waterfall & {
+        Footer: typeof WaterfallFooter;
+    };
     Logs: typeof Logs;
 };
 export {};

package/dist/src/index.d.ts

@@ -8,6 +8,7 @@
 export * from './utils';
 export * from './motion';
 export * from './components/button';
+export * from './components/date-range-picker';
 export * from './components/input';
 export * from './components/input-group';
 export * from './components/card';