@photon-ai/pho-ui 2.16.0 → 3.0.0

package/dist/src/components/date-picker/date-picker.d.ts

@@ -0,0 +1,97 @@
+import { ReactNode } from 'react';
+import { DateRange, PropsBase } from 'react-day-picker';
+import { InputSize } from '../input';
+/** The trigger wears Input's sizes so the two line up in one form. */
+export type DatePickerSize = InputSize;
+/**
+ * How fine the time is asked for, and read back. Omit it for a date alone.
+ * The value is always a `Date`; the granularity says which of its parts the
+ * viewer sets, and everything below is zeroed.
+ */
+export type DatePickerTime = "hour" | "minute" | "second";
+/**
+ * The shape to type, in this locale's own order — `mm/dd/yyyy`,
+ * `yyyy-mm-dd`, `dd.mm.yyyy`. Lowercase, the way a browser's own date field
+ * writes it, so the two paths read alike.
+ */
+export declare function dateFieldMask(locales?: Intl.LocalesArgument, time?: DatePickerTime): string;
+/**
+ * The figures in the field — `09/12/2026`, or `09/10/2026 – 09/13/2026` for a
+ * span, in the viewer's locale. An empty or half-finished range prints just
+ * the day that is settled; nothing selected prints nothing. Pass `time` to
+ * print the clock too, at the precision that was asked for.
+ *
+ * Figures rather than words (`Sep 12, 2026`) because the field is typed into:
+ * a month's name is the one part of a date nobody wants to spell.
+ */
+export declare function formatDateLabel(value: Date | DateRange | undefined, locales?: Intl.LocalesArgument, time?: DatePickerTime): string;
+interface DatePickerBaseProps {
+    /** Field label (associated for accessibility). */
+    label?: ReactNode;
+    /** Helper text below the field; rendered in the error color when `invalid`. */
+    hint?: ReactNode;
+    /**
+     * What the field shows until something is chosen.
+     * @default the shape to type, in this locale's order (`mm/dd/yyyy`)
+     */
+    placeholder?: string;
+    /** Render the invalid state (error ring + error-colored hint). */
+    invalid?: boolean;
+    disabled?: boolean;
+    /** Marks the label with the required asterisk. */
+    required?: boolean;
+    /** Size variant. @default "md" */
+    size?: DatePickerSize;
+    /**
+     * Ask for a time as well as a day, this fine. `hour` sets the hour and
+     * zeroes the rest, `minute` the hour and minute, `second` all three. Omit
+     * it and the value is midnight on the chosen day.
+     */
+    time?: DatePickerTime;
+    /** Locale for the trigger's words. Defaults to the viewer's. */
+    locales?: Intl.LocalesArgument;
+    /**
+     * Everything else React DayPicker takes — `disabled` days, `startMonth` /
+     * `endMonth`, `numberOfMonths`, `weekStartsOn`, `captionLayout`.
+     */
+    calendarProps?: PropsBase;
+    /** Id for the trigger, if the page needs its own. */
+    id?: string;
+    /** Class applied to the trigger. */
+    className?: string;
+}
+export interface DatePickerSingleProps extends DatePickerBaseProps {
+    /** @default "single" */
+    mode?: "single";
+    value?: Date;
+    defaultValue?: Date;
+    onValueChange?: (value: Date | undefined) => void;
+}
+export interface DatePickerRangeProps extends DatePickerBaseProps {
+    mode: "range";
+    value?: DateRange;
+    defaultValue?: DateRange;
+    onValueChange?: (value: DateRange | undefined) => void;
+}
+export type DatePickerProps = DatePickerSingleProps | DatePickerRangeProps;
+/**
+ * Date Picker — a field that shows the chosen date and opens a `Calendar` to
+ * change it. `mode="range"` picks a span instead of a day; the popover stays
+ * open until both ends are down.
+ *
+ * The value is a `Date` (or a `{ from, to }` range), never a string: pass
+ * `value` to control it, `defaultValue` to let it keep its own. Clearing is
+ * built in — clicking the chosen day again unsets it.
+ *
+ * `time` asks for the clock as well, to the hour, the minute, or the second.
+ *
+ * On a touch device the field hands off to the system picker — the OS wheel or
+ * dialog, which people already know — as long as the rules the page set are
+ * ones it can enforce. A weekday rule or a predicate keeps the calendar, which
+ * can; so does `mode="range"`, which no system picker offers.
+ */
+export declare function DatePicker(props: DatePickerProps): import("react").JSX.Element;
+export declare namespace DatePicker {
+    var displayName: string;
+}
+export {};

package/dist/src/components/date-picker/index.d.ts

@@ -0,0 +1,2 @@
+export { DatePicker, formatDateLabel, type DatePickerProps, type DatePickerSingleProps, type DatePickerRangeProps, type DatePickerSize, } from './date-picker';
+export type { DateRange } from 'react-day-picker';

package/dist/src/components/scroll-area/scroll-area.d.ts

@@ -17,7 +17,15 @@ declare function Content({ inset, insetTop, insetBottom, style, ref, ...props }:
     insetBottom?: number | string;
     ref?: Ref<HTMLDivElement>;
 }): import("react").JSX.Element;
-declare function Root({ className, children, ...props }: StyledProps<typeof BaseScrollArea.Root>): import("react").JSX.Element;
+declare function Root({ className, children, fade, ...props }: StyledProps<typeof BaseScrollArea.Root> & {
+    /**
+     * Progressive edge fade (blur + wash). Leave on except for code
+     * surfaces — CodeBlock is the only caller that turns it off, so
+     * glyphs hard-clip at the border.
+     * @default true
+     */
+    fade?: boolean;
+}): import("react").JSX.Element;
 declare function Viewport({ className, ref, ...props }: StyledProps<typeof BaseScrollArea.Viewport>): import("react").JSX.Element;
 declare function Scrollbar({ className, ...props }: StyledProps<typeof BaseScrollArea.Scrollbar>): import("react").JSX.Element;
 declare function Thumb({ className, ...props }: StyledProps<typeof BaseScrollArea.Thumb>): import("react").JSX.Element;

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;