footprint-explainable-ui 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,270 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/** Snapshot of a single pipeline stage — the core data shape for all components. */
+interface StageSnapshot {
+    /** Internal stage identifier */
+    stageName: string;
+    /** Human-readable label */
+    stageLabel: string;
+    /** Accumulated memory state after this stage ran */
+    memory: Record<string, unknown>;
+    /** Narrative text describing what happened */
+    narrative: string;
+    /** When this stage started (ms from pipeline start) */
+    startMs: number;
+    /** How long this stage took (ms) */
+    durationMs: number;
+    /** Execution status */
+    status?: "pending" | "active" | "done" | "error";
+}
+/** Component size variants */
+type Size = "compact" | "default" | "detailed";
+/** Common props shared by all visualization components */
+interface BaseComponentProps {
+    /** Size variant */
+    size?: Size;
+    /** Strip all built-in styles — bring your own */
+    unstyled?: boolean;
+    /** Additional CSS class name */
+    className?: string;
+    /** Inline style overrides */
+    style?: React.CSSProperties;
+}
+
+/** Default theme tokens — consumers override via CSS variables or ThemeProvider. */
+interface ThemeTokens {
+    colors?: {
+        primary?: string;
+        success?: string;
+        error?: string;
+        warning?: string;
+        bgPrimary?: string;
+        bgSecondary?: string;
+        bgTertiary?: string;
+        textPrimary?: string;
+        textSecondary?: string;
+        textMuted?: string;
+        border?: string;
+    };
+    radius?: string;
+    fontFamily?: {
+        sans?: string;
+        mono?: string;
+    };
+}
+/** Maps ThemeTokens to CSS custom property assignments. */
+declare function tokensToCSSVars(tokens: ThemeTokens): Record<string, string>;
+/** Default dark theme values (used as CSS variable fallbacks). */
+declare const defaultTokens: Required<{
+    [K in keyof ThemeTokens]-?: Required<ThemeTokens[K]>;
+}>;
+
+declare function useFootprintTheme(): ThemeTokens;
+interface FootprintThemeProps {
+    tokens?: ThemeTokens;
+    children: React.ReactNode;
+}
+/**
+ * Optional theme provider — wraps children with CSS custom properties.
+ * Consumers can also just set --fp-* CSS variables directly.
+ */
+declare function FootprintTheme({ tokens, children }: FootprintThemeProps): react_jsx_runtime.JSX.Element;
+
+/** Cool dark theme (the library default) */
+declare const coolDark: ThemeTokens;
+/** Warm dark theme — charcoal-purple palette */
+declare const warmDark: ThemeTokens;
+/** Warm light theme — cream/peach palette */
+declare const warmLight: ThemeTokens;
+/** All built-in theme presets */
+declare const themePresets: {
+    readonly coolDark: ThemeTokens;
+    readonly warmDark: ThemeTokens;
+    readonly warmLight: ThemeTokens;
+};
+type ThemePresetName = keyof typeof themePresets;
+
+interface MemoryInspectorProps extends BaseComponentProps {
+    /** Single memory object or snapshots (will accumulate up to selectedIndex) */
+    data?: Record<string, unknown>;
+    /** When using snapshots mode, pass these instead of data */
+    snapshots?: StageSnapshot[];
+    /** Index to accumulate up to (for time-travel) */
+    selectedIndex?: number;
+    /** Show data types alongside values */
+    showTypes?: boolean;
+    /** Highlight keys that are new at this step */
+    highlightNew?: boolean;
+}
+/**
+ * Displays pipeline memory state as formatted JSON.
+ * Supports both static (data prop) and time-travel (snapshots + selectedIndex) modes.
+ */
+declare function MemoryInspector({ data, snapshots, selectedIndex, showTypes, highlightNew, size, unstyled, className, style, }: MemoryInspectorProps): react_jsx_runtime.JSX.Element;
+
+interface NarrativeLogProps extends BaseComponentProps {
+    /** Snapshots to display narratives from */
+    snapshots: StageSnapshot[];
+    /** Show narratives up to this index (for time-travel sync) */
+    selectedIndex?: number;
+    /** Show a single narrative string (simple mode) */
+    narrative?: string;
+}
+/**
+ * Timeline-style execution log showing what happened at each stage.
+ * Supports both full snapshots mode and single-narrative mode.
+ */
+declare function NarrativeLog({ snapshots, selectedIndex, narrative, size, unstyled, className, style, }: NarrativeLogProps): react_jsx_runtime.JSX.Element;
+
+interface NarrativeTraceProps extends BaseComponentProps {
+    /** All narrative lines (full trace) */
+    narrative: string[];
+    /** Number of lines currently revealed (for progressive reveal). Defaults to all. */
+    revealedCount?: number;
+    /** Start with all groups collapsed */
+    defaultCollapsed?: boolean;
+    /** Called when user clicks a stage header */
+    onStageClick?: (headerIndex: number) => void;
+}
+declare function NarrativeTrace({ narrative, revealedCount, defaultCollapsed, onStageClick, size, unstyled, className, style, }: NarrativeTraceProps): react_jsx_runtime.JSX.Element;
+
+interface GanttTimelineProps extends BaseComponentProps {
+    /** Stage snapshots with timing info */
+    snapshots: StageSnapshot[];
+    /** Currently selected stage index */
+    selectedIndex?: number;
+    /** Callback when a stage bar is clicked */
+    onSelect?: (index: number) => void;
+}
+/**
+ * Horizontal Gantt-style timeline showing stage durations and overlap.
+ * Great for performance analysis of pipeline execution.
+ */
+declare function GanttTimeline({ snapshots, selectedIndex, onSelect, size, unstyled, className, style, }: GanttTimelineProps): react_jsx_runtime.JSX.Element;
+
+interface SnapshotPanelProps extends BaseComponentProps {
+    /** Stage snapshots from pipeline execution */
+    snapshots: StageSnapshot[];
+    /** Show the Gantt timeline */
+    showGantt?: boolean;
+    /** Show the time-travel scrubber */
+    showScrubber?: boolean;
+    /** Title override */
+    title?: string;
+}
+/**
+ * All-in-one panel: time-travel scrubber + memory inspector + narrative log + gantt.
+ * Drop this into any page to make a pipeline run inspectable.
+ */
+declare function SnapshotPanel({ snapshots, showGantt, showScrubber, title, size, unstyled, className, style, }: SnapshotPanelProps): react_jsx_runtime.JSX.Element;
+
+interface DiffEntry {
+    key: string;
+    type: "added" | "removed" | "changed" | "unchanged";
+    oldValue?: unknown;
+    newValue?: unknown;
+}
+interface ScopeDiffProps extends BaseComponentProps {
+    /** Memory state before the current stage */
+    previous: Record<string, unknown> | null;
+    /** Memory state after the current stage */
+    current: Record<string, unknown>;
+    /** Hide unchanged keys (default: false) */
+    hideUnchanged?: boolean;
+}
+declare function ScopeDiff({ previous, current, hideUnchanged, size, unstyled, className, style, }: ScopeDiffProps): react_jsx_runtime.JSX.Element;
+
+interface ResultPanelProps extends BaseComponentProps {
+    /** Final pipeline output / shared state */
+    data: Record<string, unknown> | null;
+    /** Optional console log lines */
+    logs?: string[];
+    /** Hide console section (default: false) */
+    hideConsole?: boolean;
+}
+declare function ResultPanel({ data, logs, hideConsole, size, unstyled, className, style, }: ResultPanelProps): react_jsx_runtime.JSX.Element;
+
+interface TimeTravelControlsProps extends BaseComponentProps {
+    /** Stage snapshots */
+    snapshots: StageSnapshot[];
+    /** Currently selected stage index */
+    selectedIndex: number;
+    /** Callback when selected index changes */
+    onIndexChange: (index: number) => void;
+    /** Enable auto-play with Gantt-proportional timing */
+    autoPlayable?: boolean;
+}
+declare function TimeTravelControls({ snapshots, selectedIndex, onIndexChange, autoPlayable, size, unstyled, className, style, }: TimeTravelControlsProps): react_jsx_runtime.JSX.Element;
+
+type ShellTab = "result" | "explainable" | "ai-compatible";
+interface ExplainableShellProps extends BaseComponentProps {
+    /** Stage snapshots for time-travel visualization */
+    snapshots: StageSnapshot[];
+    /** Final pipeline result data */
+    resultData?: Record<string, unknown> | null;
+    /** Console log lines */
+    logs?: string[];
+    /** Combined narrative lines */
+    narrative?: string[];
+    /** Which tabs to show (default: all three) */
+    tabs?: ShellTab[];
+    /** Initially active tab */
+    defaultTab?: ShellTab;
+    /** Hide console in result tab */
+    hideConsole?: boolean;
+    /** Custom content to render in each tab slot */
+    renderFlowchart?: (props: {
+        snapshots: StageSnapshot[];
+        selectedIndex: number;
+        onNodeClick?: (index: number) => void;
+    }) => React.ReactNode;
+}
+declare function ExplainableShell({ snapshots, resultData, logs, narrative, tabs, defaultTab, hideConsole, renderFlowchart, size, unstyled, className, style, }: ExplainableShellProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Shape of FootPrint's RuntimeSnapshot (from FlowChartExecutor.getSnapshot()).
+ * We define it here instead of importing to avoid a hard dependency on footprintjs.
+ */
+interface RuntimeStageSnapshot {
+    id: string;
+    name?: string;
+    isDecider?: boolean;
+    isFork?: boolean;
+    logs: Record<string, unknown>;
+    errors: Record<string, unknown>;
+    metrics: Record<string, unknown>;
+    evals: Record<string, unknown>;
+    flowMessages?: unknown[];
+    next?: RuntimeStageSnapshot;
+    children?: RuntimeStageSnapshot[];
+}
+interface RuntimeSnapshot {
+    sharedState: Record<string, unknown>;
+    executionTree: RuntimeStageSnapshot;
+    commitLog: unknown[];
+}
+/**
+ * Converts a FootPrint RuntimeSnapshot into a flat array of StageSnapshots
+ * suitable for visualization components.
+ *
+ * Usage:
+ * ```ts
+ * const executor = new FlowChartExecutor(chart);
+ * await executor.run();
+ * const snapshots = toVisualizationSnapshots(executor.getSnapshot());
+ * ```
+ */
+declare function toVisualizationSnapshots(runtime: RuntimeSnapshot): StageSnapshot[];
+/**
+ * Creates StageSnapshots from simple arrays (when you don't have a RuntimeSnapshot).
+ * Useful for testing or custom data sources.
+ */
+declare function createSnapshots(stages: Array<{
+    name: string;
+    label?: string;
+    memory?: Record<string, unknown>;
+    narrative?: string;
+    durationMs?: number;
+}>): StageSnapshot[];
+
+export { type BaseComponentProps, type DiffEntry, ExplainableShell, type ExplainableShellProps, FootprintTheme, GanttTimeline, type GanttTimelineProps, MemoryInspector, type MemoryInspectorProps, NarrativeLog, type NarrativeLogProps, NarrativeTrace, type NarrativeTraceProps, ResultPanel, type ResultPanelProps, ScopeDiff, type ScopeDiffProps, type ShellTab, type Size, SnapshotPanel, type SnapshotPanelProps, type StageSnapshot, type ThemePresetName, type ThemeTokens, TimeTravelControls, type TimeTravelControlsProps, coolDark, createSnapshots, defaultTokens, themePresets, toVisualizationSnapshots, tokensToCSSVars, useFootprintTheme, warmDark, warmLight };