@mastra/playground-ui 23.0.2 → 24.0.0-alpha.0

package/dist/src/domains/traces/components/trace-details-view.d.ts

@@ -0,0 +1,18 @@
+import { LightSpanRecord } from '@mastra/core/storage';
+export interface TraceDetailsViewProps {
+    traceId: string;
+    /** Lightweight spans for the trace. Caller fetches via useTraceLightSpans. */
+    spans: LightSpanRecord[] | undefined;
+    isLoading?: boolean;
+    onClose: () => void;
+    /** Called when the user clicks a span in the timeline. Toggling a selected span off passes undefined. */
+    onSpanSelect?: (spanId: string | undefined) => void;
+    /** Fully controlled selection — the span to highlight. Pass whatever the parent's source of truth is. */
+    selectedSpanId?: string | null;
+}
+/**
+ * Compact trace panel using `DataDetailsPanel` (popover-style). Renders the timeline only —
+ * no trace header KV, no evaluate/save actions. Use this for inline trace inspection from a
+ * list page (e.g. the Logs page). For the full-width trace view, use `TraceDataPanelView`.
+ */
+export declare function TraceDetailsView({ traceId, spans, isLoading, onClose, onSpanSelect, selectedSpanId, }: TraceDetailsViewProps): import("react/jsx-runtime").JSX.Element;

package/dist/src/domains/traces/components/trace-keys-and-values.d.ts

@@ -0,0 +1,16 @@
+/** Lightweight root-span fields available from `useTraceLightSpans`. */
+type RootSpanSummary = {
+    entityId?: string | null;
+    entityName?: string | null;
+    entityType?: string | null;
+    startedAt: Date | string;
+    endedAt?: Date | string | null;
+    error?: unknown;
+};
+export interface TraceKeysAndValuesProps {
+    rootSpan: RootSpanSummary;
+    numOfCol?: 1 | 2 | 3;
+    className?: string;
+}
+export declare function TraceKeysAndValues({ rootSpan, numOfCol, className }: TraceKeysAndValuesProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/src/domains/traces/components/trace-timeline-span.d.ts

@@ -0,0 +1,18 @@
+import { UISpan } from '../types';
+type TraceTimelineSpanProps = {
+    span: UISpan;
+    depth?: number;
+    onSpanClick?: (id: string) => void;
+    selectedSpanId?: string;
+    isLastChild?: boolean;
+    overallLatency?: number;
+    overallStartTime?: string;
+    fadedTypes?: string[];
+    searchPhrase?: string;
+    featuredSpanIds?: string[];
+    expandedSpanIds?: string[];
+    setExpandedSpanIds?: React.Dispatch<React.SetStateAction<string[]>>;
+    chartWidth?: 'wide' | 'default';
+};
+export declare function TraceTimelineSpan({ span, depth, onSpanClick, selectedSpanId, isLastChild, overallLatency, overallStartTime, fadedTypes, searchPhrase, featuredSpanIds, expandedSpanIds, setExpandedSpanIds, chartWidth, }: TraceTimelineSpanProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/src/domains/traces/components/trace-timeline.d.ts

@@ -0,0 +1,15 @@
+import { Dispatch, SetStateAction } from '../../../../node_modules/@types/react';
+import { UISpan } from '../types';
+type TraceTimelineProps = {
+    hierarchicalSpans: UISpan[];
+    onSpanClick: (id: string) => void;
+    selectedSpanId?: string;
+    isLoading?: boolean;
+    fadedTypes?: string[];
+    expandedSpanIds?: string[];
+    setExpandedSpanIds?: Dispatch<SetStateAction<string[]>>;
+    featuredSpanIds?: string[];
+    chartWidth?: 'wide' | 'default';
+};
+export declare function TraceTimeline({ hierarchicalSpans, onSpanClick, selectedSpanId, isLoading, fadedTypes, expandedSpanIds, setExpandedSpanIds, featuredSpanIds, chartWidth, }: TraceTimelineProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/src/domains/traces/components/traces-error-content.d.ts

@@ -0,0 +1,16 @@
+export interface TracesErrorContentProps {
+    /** The error from a useTraces / useTraceLightSpans / etc. query. */
+    error: unknown;
+    /** Passed to PermissionDenied (e.g. 'traces' / 'trace'). */
+    resource: string;
+    /** Title shown on the generic ErrorState fallback. */
+    errorTitle: string;
+}
+/**
+ * Renders the appropriate fallback content for a traces-related query error:
+ * `<SessionExpired />` for 401, `<PermissionDenied />` for 403, otherwise `<ErrorState />`.
+ *
+ * The consumer wraps it in whatever layout they want (NoDataPageLayout for the list page,
+ * PageLayout.MainArea for the detail page, etc.) — this component only owns the 3-branch decision.
+ */
+export declare function TracesErrorContent({ error, resource, errorTitle }: TracesErrorContentProps): import("react/jsx-runtime").JSX.Element;

package/dist/src/domains/traces/components/traces-layout.d.ts

@@ -0,0 +1,18 @@
+import { ReactNode } from '../../../../node_modules/@types/react';
+export interface TracesLayoutProps {
+    /** The trace list (left column). */
+    listSlot: ReactNode;
+    /** The trace data panel (right column, top). When null/undefined, the whole right column collapses. */
+    tracePanelSlot?: ReactNode;
+    /** The span data panel (right column, middle). Only rendered when truthy. */
+    spanPanelSlot?: ReactNode;
+    /** The score data panel (right column, bottom). Only rendered when truthy. */
+    scorePanelSlot?: ReactNode;
+    /** When the trace panel is collapsed, the right column's grid-rows squash the trace row to `auto`. */
+    traceCollapsed?: boolean;
+}
+/**
+ * Pure 2-column layout shell for the traces page. Owns no state and fetches no data — pass slots in.
+ * Right-column row template adapts based on which panels are present.
+ */
+export declare function TracesLayout({ listSlot, tracePanelSlot, spanPanelSlot, scorePanelSlot, traceCollapsed, }: TracesLayoutProps): import("react/jsx-runtime").JSX.Element;

package/dist/src/domains/traces/components/traces-list-view.d.ts

@@ -0,0 +1,39 @@
+/** Span attributes fields the list view reads directly. Extra unknown keys are allowed so callers
+ *  can pass the full attributes record from @mastra/core/storage without mapping. */
+export type TraceAttributes = {
+    status?: string | null;
+    agentId?: string | null;
+    workflowId?: string | null;
+    [key: string]: unknown;
+};
+export type TracesListViewTrace = {
+    traceId: string;
+    name: string;
+    entityType?: string | null;
+    entityId?: string | null;
+    entityName?: string | null;
+    attributes?: TraceAttributes | null;
+    input?: unknown;
+    startedAt?: Date | string | null;
+    createdAt: Date | string;
+    threadId?: string | null;
+};
+export type TracesListViewProps = {
+    traces: TracesListViewTrace[];
+    isLoading?: boolean;
+    isFetchingNextPage?: boolean;
+    hasNextPage?: boolean;
+    setEndOfListElement?: (element: HTMLDivElement | null) => void;
+    filtersApplied?: boolean;
+    /** Currently featured/selected trace — its row gets the highlighted background. */
+    featuredTraceId?: string | null;
+    /** Called when a row is clicked. The current selection logic (toggle on same id) is the consumer's call. */
+    onTraceClick: (trace: TracesListViewTrace) => void;
+    groupByThread?: boolean;
+    threadTitles?: Record<string, string>;
+};
+/**
+ * Pure presentational list. Renders the TracesDataList primitive with rows, optional thread grouping,
+ * empty state, and infinite-paging loader. Owns no state.
+ */
+export declare function TracesListView({ traces, isLoading, isFetchingNextPage, hasNextPage, setEndOfListElement, filtersApplied, featuredTraceId, onTraceClick, groupByThread, threadTitles, }: TracesListViewProps): import("react/jsx-runtime").JSX.Element;

package/dist/src/domains/traces/components/traces-toolbar.d.ts

@@ -0,0 +1,19 @@
+import { PropertyFilterField, PropertyFilterToken } from '../../../ds/components/PropertyFilter/types';
+type TracesToolbarProps = {
+    /** Keep all filter pills but reset each value to its neutral state
+     *  ('' for text, 'Any' for single-select, [] for multi-select). */
+    onClear?: () => void;
+    /** Fully remove all filter pills. */
+    onRemoveAll?: () => void;
+    onSave?: () => void;
+    /** When provided, an extra "Remove saved filters" option is shown —
+     *  wire it up only when there is actually a saved set to remove. */
+    onRemoveSaved?: () => void;
+    isLoading?: boolean;
+    filterFields: PropertyFilterField[];
+    filterTokens: PropertyFilterToken[];
+    onFilterTokensChange: (tokens: PropertyFilterToken[]) => void;
+    autoFocusFilterFieldId?: string;
+};
+export declare function TracesToolbar({ onClear, onRemoveAll, onSave, onRemoveSaved, isLoading, filterFields, filterTokens, onFilterTokensChange, autoFocusFilterFieldId, }: TracesToolbarProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/src/domains/traces/hooks/get-all-span-ids.d.ts

@@ -0,0 +1,3 @@
+import { UISpan } from '../types';
+export declare function getSpanDescendantIds(span: UISpan): string[];
+export declare function getAllSpanIds(spans: UISpan[]): string[];

package/dist/src/domains/traces/hooks/index.d.ts

@@ -0,0 +1,13 @@
+export { getAllSpanIds, getSpanDescendantIds } from './get-all-span-ids';
+export { useSpanDetail } from './use-span-detail';
+export { useTraceLightSpans } from './use-trace-light-spans';
+export { useTraceSpans } from './use-trace-spans';
+export { useTraces } from './use-traces';
+export { useTags } from './use-tags';
+export { useEntityNames } from './use-entity-names';
+export { useEnvironments } from './use-environments';
+export { useServiceNames } from './use-service-names';
+export { useTraceSpanNavigation } from './use-trace-span-navigation';
+export { useTraceListNavigation } from './use-trace-list-navigation';
+export { useTraceUrlState, type UseTraceUrlStateResult, type UseTraceUrlStateOptions, type SetURLSearchParamsLike, } from './use-trace-url-state';
+export { useTraceFilterPersistence, type UseTraceFilterPersistenceResult, type TraceFilterPersistenceOptions, } from './use-trace-filter-persistence';

package/dist/src/domains/traces/hooks/use-entity-names.d.ts

@@ -0,0 +1,7 @@
+import { EntityType } from '@mastra/core/observability';
+type UseEntityNamesOptions = {
+    entityType?: EntityType;
+    rootOnly?: boolean;
+};
+export declare const useEntityNames: ({ entityType, rootOnly }?: UseEntityNamesOptions) => import('@tanstack/react-query').UseQueryResult<string[], Error>;
+export {};

package/dist/src/domains/traces/hooks/use-environments.d.ts

@@ -0,0 +1 @@
+export declare const useEnvironments: () => import('@tanstack/react-query').UseQueryResult<string[], Error>;

package/dist/src/domains/traces/hooks/use-service-names.d.ts

@@ -0,0 +1 @@
+export declare const useServiceNames: () => import('@tanstack/react-query').UseQueryResult<string[], Error>;

package/dist/src/domains/traces/hooks/use-span-detail.d.ts

@@ -0,0 +1,46 @@
+export declare function useSpanDetail(traceId: string | null | undefined, spanId: string | null | undefined): import('@tanstack/react-query').UseQueryResult<{
+    span: {
+        createdAt: Date;
+        updatedAt: Date | null;
+        name: string;
+        spanType: import('@mastra/core/observability').SpanType;
+        isEvent: boolean;
+        startedAt: Date;
+        traceId: string;
+        spanId: string;
+        experimentId?: string | null | undefined;
+        attributes?: Record<string, unknown> | null | undefined;
+        links?: unknown[] | null | undefined;
+        input?: unknown;
+        output?: unknown;
+        error?: unknown;
+        endedAt?: Date | null | undefined;
+        requestContext?: Record<string, unknown> | null | undefined;
+        metadata?: Record<string, unknown> | null | undefined;
+        tags?: string[] | null | undefined;
+        source?: string | null | undefined;
+        entityType?: import('@mastra/core/storage').EntityType | null | undefined;
+        entityId?: string | null | undefined;
+        entityName?: string | null | undefined;
+        parentEntityType?: import('@mastra/core/storage').EntityType | null | undefined;
+        parentEntityId?: string | null | undefined;
+        parentEntityName?: string | null | undefined;
+        rootEntityType?: import('@mastra/core/storage').EntityType | null | undefined;
+        rootEntityId?: string | null | undefined;
+        rootEntityName?: string | null | undefined;
+        userId?: string | null | undefined;
+        organizationId?: string | null | undefined;
+        resourceId?: string | null | undefined;
+        runId?: string | null | undefined;
+        sessionId?: string | null | undefined;
+        threadId?: string | null | undefined;
+        requestId?: string | null | undefined;
+        environment?: string | null | undefined;
+        serviceName?: string | null | undefined;
+        scope?: Record<string, unknown> | null | undefined;
+        entityVersionId?: string | null | undefined;
+        parentEntityVersionId?: string | null | undefined;
+        rootEntityVersionId?: string | null | undefined;
+        parentSpanId?: string | null | undefined;
+    };
+}, Error>;

package/dist/src/domains/traces/hooks/use-tags.d.ts

@@ -0,0 +1 @@
+export declare const useTags: () => import('@tanstack/react-query').UseQueryResult<string[], Error>;

package/dist/src/domains/traces/hooks/use-trace-filter-persistence.d.ts

@@ -0,0 +1,31 @@
+import { SetURLSearchParamsLike } from './use-trace-url-state';
+export interface TraceFilterPersistenceOptions {
+    /** Override the localStorage key. Default: 'mastra:traces:saved-filters'. */
+    storageKey?: string;
+    /** Toast text overrides; pass `false` to suppress the toast entirely. */
+    messages?: {
+        saved?: string | false;
+        cleared?: string | false;
+    };
+    /** Skip the once-on-mount hydration from localStorage. Default: false (hydration runs). */
+    skipHydration?: boolean;
+}
+export interface UseTraceFilterPersistenceResult {
+    /** True when localStorage has a previously saved filter set. */
+    hasSavedFilters: boolean;
+    /** Persist the current URL filter params to localStorage. */
+    handleSave: () => void;
+    /** Forget the saved filter set. */
+    handleRemoveSaved: () => void;
+}
+/**
+ * Owns the localStorage save/restore lifecycle for trace filters:
+ * - tracks `hasSavedFilters`
+ * - exposes `handleSave` / `handleRemoveSaved` (with toast feedback)
+ * - hydrates the URL from saved filters once on mount, but only if the URL is filter-clean
+ *   (so a shared link / direct nav with explicit filters wins over the saved set)
+ *
+ * Pass `storageKey` to scope persistence (e.g. per-project). Pass `messages.{saved,cleared} = false`
+ * to suppress the toast.
+ */
+export declare function useTraceFilterPersistence(searchParams: URLSearchParams, setSearchParams: SetURLSearchParamsLike, options?: TraceFilterPersistenceOptions): UseTraceFilterPersistenceResult;

package/dist/src/domains/traces/hooks/use-trace-light-spans.d.ts

@@ -0,0 +1,19 @@
+export declare function useTraceLightSpans(traceId: string | null | undefined): import('@tanstack/react-query').UseQueryResult<{
+    traceId: string;
+    spans: {
+        createdAt: Date;
+        updatedAt: Date | null;
+        name: string;
+        spanType: import('@mastra/core/observability').SpanType;
+        isEvent: boolean;
+        startedAt: Date;
+        traceId: string;
+        spanId: string;
+        parentSpanId?: string | null | undefined;
+        endedAt?: Date | null | undefined;
+        error?: unknown;
+        entityType?: import('@mastra/core/storage').EntityType | null | undefined;
+        entityId?: string | null | undefined;
+        entityName?: string | null | undefined;
+    }[];
+}, Error>;

package/dist/src/domains/traces/hooks/use-trace-list-navigation.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Derives previous/next *trace* navigation handlers from the current traces list and the featured
+ * trace id. Returns undefined for handlers that are out of bounds so the consumer can render
+ * disabled UI. Mirrors the shape of `useTraceSpanNavigation`.
+ */
+export declare function useTraceListNavigation<T extends {
+    traceId: string;
+}>(traces: T[], featuredTraceId: string | undefined, onTraceChange: (traceId: string) => void): {
+    featuredTraceIdx: number;
+    handlePreviousTrace: (() => void) | undefined;
+    handleNextTrace: (() => void) | undefined;
+};

package/dist/src/domains/traces/hooks/use-trace-span-navigation.d.ts

@@ -0,0 +1,10 @@
+import { LightSpanRecord } from '@mastra/core/storage';
+/**
+ * Derives previous/next span navigation handlers from a trace's lightweight spans.
+ * Returns undefined for handlers that are out of bounds so the consumer can render disabled UI.
+ */
+export declare function useTraceSpanNavigation(lightSpans: LightSpanRecord[] | undefined, featuredSpanId: string | null | undefined, onSpanChange: (spanId: string) => void): {
+    handlePreviousSpan: (() => void) | undefined;
+    handleNextSpan: (() => void) | undefined;
+    timelineSpanIds: string[];
+};

package/dist/src/domains/traces/hooks/use-trace-spans.d.ts

@@ -0,0 +1,47 @@
+export declare function useTraceSpans(traceId: string | null | undefined): import('@tanstack/react-query').UseQueryResult<{
+    traceId: string;
+    spans: {
+        createdAt: Date;
+        updatedAt: Date | null;
+        name: string;
+        spanType: import('@mastra/core/observability').SpanType;
+        isEvent: boolean;
+        startedAt: Date;
+        traceId: string;
+        spanId: string;
+        experimentId?: string | null | undefined;
+        attributes?: Record<string, unknown> | null | undefined;
+        links?: unknown[] | null | undefined;
+        input?: unknown;
+        output?: unknown;
+        error?: unknown;
+        endedAt?: Date | null | undefined;
+        requestContext?: Record<string, unknown> | null | undefined;
+        metadata?: Record<string, unknown> | null | undefined;
+        tags?: string[] | null | undefined;
+        source?: string | null | undefined;
+        entityType?: import('@mastra/core/storage').EntityType | null | undefined;
+        entityId?: string | null | undefined;
+        entityName?: string | null | undefined;
+        parentEntityType?: import('@mastra/core/storage').EntityType | null | undefined;
+        parentEntityId?: string | null | undefined;
+        parentEntityName?: string | null | undefined;
+        rootEntityType?: import('@mastra/core/storage').EntityType | null | undefined;
+        rootEntityId?: string | null | undefined;
+        rootEntityName?: string | null | undefined;
+        userId?: string | null | undefined;
+        organizationId?: string | null | undefined;
+        resourceId?: string | null | undefined;
+        runId?: string | null | undefined;
+        sessionId?: string | null | undefined;
+        threadId?: string | null | undefined;
+        requestId?: string | null | undefined;
+        environment?: string | null | undefined;
+        serviceName?: string | null | undefined;
+        scope?: Record<string, unknown> | null | undefined;
+        entityVersionId?: string | null | undefined;
+        parentEntityVersionId?: string | null | undefined;
+        rootEntityVersionId?: string | null | undefined;
+        parentSpanId?: string | null | undefined;
+    }[];
+}, Error>;

package/dist/src/domains/traces/hooks/use-trace-url-state.d.ts

@@ -0,0 +1,53 @@
+import { SpanTab, TraceDatePreset } from '../index';
+import { EntityOptions, TraceStatusFilter } from '../trace-filters';
+import { PropertyFilterToken } from '../../../ds/components/PropertyFilter/types';
+/** Minimal interface compatible with react-router's `setSearchParams`. */
+export type SetURLSearchParamsLike = (next: URLSearchParams | ((prev: URLSearchParams) => URLSearchParams), options?: {
+    replace?: boolean;
+    preventScrollReset?: boolean;
+    state?: unknown;
+}) => void;
+export interface UseTraceUrlStateOptions {
+    /** Called after `handleRemoveAll` clears all filter URL params. Use this to reset page-local
+     *  UI state (e.g. a "group by thread" toggle) without wrapping the handler. */
+    onRemoveAll?: () => void;
+}
+export interface UseTraceUrlStateResult {
+    searchParams: URLSearchParams;
+    setSearchParams: SetURLSearchParamsLike;
+    datePreset: TraceDatePreset;
+    selectedDateFrom: Date | undefined;
+    selectedDateTo: Date | undefined;
+    /** Synchronously-updated ref of the latest preset. Used to ignore onDateChange callbacks
+     *  the date picker fires after a non-custom preset switch. */
+    datePresetRef: React.MutableRefObject<TraceDatePreset>;
+    traceIdParam: string | undefined;
+    spanIdParam: string | undefined;
+    spanTabParam: SpanTab | undefined;
+    scoreIdParam: string | undefined;
+    selectedEntityOption: EntityOptions | undefined;
+    selectedStatus: TraceStatusFilter | undefined;
+    filterTokens: PropertyFilterToken[];
+    handleTraceClick: (traceId: string) => void;
+    /** Convenience: clears the featured trace selection. Equivalent to `handleTraceClick('')`. */
+    handleTraceClose: () => void;
+    handleSpanChange: (spanId: string | null) => void;
+    /** Convenience: clears the featured span selection. Equivalent to `handleSpanChange(null)`. */
+    handleSpanClose: () => void;
+    handleSpanTabChange: (tab: SpanTab) => void;
+    handleScoreChange: (scoreId: string | null) => void;
+    handleFilterTokensChange: (nextTokens: PropertyFilterToken[]) => void;
+    handleDateChange: (value: Date | undefined, type: 'from' | 'to') => void;
+    handleDatePresetChange: (preset: TraceDatePreset) => void;
+    handleRemoveAll: () => void;
+    /** Lower-level helper used by `handleClear`: writes a token set and clears the trace/span selection. */
+    applyFilterTokens: (tokens: PropertyFilterToken[]) => void;
+}
+/**
+ * Owns all URL-derived state and URL-modifying handlers for the traces page. Routing-agnostic —
+ * pass `searchParams` and `setSearchParams` from whichever router the consumer uses.
+ *
+ * Stays focused on URL state: localStorage save/restore, filter discovery, and the error-view
+ * short-circuit are intentionally NOT part of this hook so consumers can swap them independently.
+ */
+export declare function useTraceUrlState(searchParams: URLSearchParams, setSearchParams: SetURLSearchParamsLike, options?: UseTraceUrlStateOptions): UseTraceUrlStateResult;