footprint-explainable-ui

Themeable React components for visualizing footprintjs pipeline execution — time-travel debugging, flowchart overlays, subflow drill-down, and collapsible detail panels.

Install

npm install footprint-explainable-ui

Peer dependencies: react >= 18, react-dom >= 18

For flowchart components, also install:

npm install @xyflow/react

Entry Points

| Import path | What it provides | |---|---| | footprint-explainable-ui | Core components, themes, adapters | | footprint-explainable-ui/flowchart | Flowchart visualization (requires @xyflow/react) |

Quick Start

1. Convert execution data to snapshots

import { FlowChartExecutor } from "footprintjs";
import { toVisualizationSnapshots } from "footprint-explainable-ui";

const executor = new FlowChartExecutor(chart);
await executor.run({ input: data });

const snapshots = toVisualizationSnapshots(
  executor.getSnapshot(),
  executor.getNarrativeEntries(), // optional — enables rich narrative
);

2. Render with the all-in-one shell

import { ExplainableShell } from "footprint-explainable-ui";
import { TracedFlowchartView } from "footprint-explainable-ui/flowchart";

function DebugView({ snapshots, spec, narrative, narrativeEntries }) {
  return (
    <ExplainableShell
      snapshots={snapshots}
      spec={spec}
      narrative={narrative}
      narrativeEntries={narrativeEntries}
      title="My Pipeline"
      panelLabels={{ topology: "What Ran", details: "What Happened", timeline: "How Long" }}
      renderFlowchart={({ spec, snapshots, selectedIndex, onNodeClick }) => (
        <TracedFlowchartView
          spec={spec}
          snapshots={snapshots}
          snapshotIndex={selectedIndex}
          onNodeClick={onNodeClick}
        />
      )}
    />
  );
}

This gives you:

• Flowchart (center) — execution path overlay, click subflow nodes to drill-down
• Topology panel (left) — subflow tree navigator, collapsible via VLinePill handle
• Details panel (right) — Memory state + Narrative tabs, collapsible
• Timeline (bottom) — Gantt-style stage durations, collapsible
• Time-travel slider — scrub through execution steps
• Breadcrumbs — navigate back from subflow drill-down
• Mobile responsive — auto-stacks vertically below 640px

3. Or compose individual components

import {
  TimeTravelControls,
  MemoryInspector,
  ScopeDiff,
  GanttTimeline,
  NarrativeTrace,
} from "footprint-explainable-ui";

function MyDebugger({ snapshots }) {
  const [idx, setIdx] = useState(0);
  const current = snapshots[idx];
  const previous = idx > 0 ? snapshots[idx - 1] : null;

  return (
    <>
      <TimeTravelControls
        snapshots={snapshots}
        selectedIndex={idx}
        onIndexChange={setIdx}
      />
      <MemoryInspector snapshots={snapshots} selectedIndex={idx} />
      <ScopeDiff
        previous={previous?.memory ?? null}
        current={current.memory}
        hideUnchanged
      />
      <NarrativeTrace narrative={snapshots.map(s => s.narrative)} />
      <GanttTimeline snapshots={snapshots} selectedIndex={idx} onSelect={setIdx} />
    </>
  );
}

ExplainableShell

The all-in-one orchestrator. Handles time-travel, subflow drill-down, memory/narrative panels, and responsive layout.

Props

| Prop | Type | Default | Description | |---|---|---|---| | snapshots | StageSnapshot[] | required | Visualization snapshots | | spec | SpecNode \| null | — | Pipeline spec (enables flowchart + subflow tree) | | title | string | "Flowchart" | Breadcrumb root label | | narrative | string[] | — | Flat narrative lines | | narrativeEntries | NarrativeEntry[] | — | Structured narrative (rich rendering) | | panelLabels | PanelLabels | { topology: "Topology", details: "Details", timeline: "Timeline" } | Customize collapsible pill labels | | defaultExpanded | DefaultExpanded | { details: true } | Which panels start open | | tabs | ShellTab[] | ["result", "explainable"] | Visible tabs | | renderFlowchart | (props) => ReactNode | — | Flowchart renderer (pass TracedFlowchartView) | | resultData | Record<string, unknown> | — | Final output data for Result tab | | size | "compact" \| "default" \| "detailed" | "default" | Size variant | | unstyled | boolean | false | Strip styles, render data-fp attributes |

Panel Labels

Customize the text on collapsible pill buttons. Semantic keys — not tied to position:

<ExplainableShell
  panelLabels={{
    topology: "What Ran",      // left panel (subflow tree)
    details: "What Happened",  // right panel (memory/narrative)
    timeline: "How Long",      // bottom panel (Gantt)
  }}
/>

Default Expanded

Control which panels start open. Desktop default: details panel open (flowchart + memory = the library's unique value). For mobile, pass all false:

// Desktop (default) — memory panel open
<ExplainableShell snapshots={...} spec={...} />

// Mobile — all collapsed, flowchart fills screen
<ExplainableShell
  snapshots={...}
  defaultExpanded={{ details: false }}
/>

// Everything open
<ExplainableShell
  snapshots={...}
  defaultExpanded={{ topology: true, details: true, timeline: true }}
/>

Responsive Layout

The shell auto-detects container width via ResizeObserver:

• Desktop (≥640px): 3-column layout — SubflowTree | Flowchart | Memory/Narrative. Side panels collapse to VLinePill handles.
• Mobile (<640px): Stacked vertical — Flowchart (350px) → collapsible HLinePill sections. All panels auto-collapse on narrow.

Collapsible Panel UX

All panels use the line + pill pattern:

• Collapsed: Thin divider line with a centered pill button (label + arrow)
• Expanded: Full content with a pill handle on the closing edge
• VLinePill (left/right panels): Vertical line with centered vertical pill. side prop controls arrow direction.
• HLinePill (bottom timeline): Horizontal line with centered pill.

Flowchart Visualization

Import from footprint-explainable-ui/flowchart:

TracedFlowchartView (recommended)

Self-contained flowchart renderer. Handles overlay computation, auto-fitView on resize.

import { TracedFlowchartView } from "footprint-explainable-ui/flowchart";

<div style={{ height: 400 }}>
  <TracedFlowchartView
    spec={spec}
    snapshots={snapshots}
    snapshotIndex={idx}
    onNodeClick={(nodeId) => handleClick(nodeId)}
  />
</div>

Without snapshots, renders a plain static flowchart. With snapshots, shows the execution trace path with Google Maps-style glow.

Auto-fitView: The flowchart automatically calls fitView() when its container resizes (e.g. panel expand/collapse).

Manual control with specToReactFlow

import { specToReactFlow, StageNode, type ExecutionOverlay } from "footprint-explainable-ui/flowchart";
import { ReactFlow } from "@xyflow/react";

const overlay: ExecutionOverlay = {
  doneStages: new Set(["LoadOrder", "ProcessPayment"]),
  activeStage: "ShipOrder",
  executedStages: new Set(["LoadOrder", "ProcessPayment", "ShipOrder"]),
  executionOrder: ["LoadOrder", "ProcessPayment", "ShipOrder"],
};

const { nodes, edges } = specToReactFlow(spec, overlay);

<ReactFlow
  nodes={nodes}
  edges={edges}
  nodeTypes={{ stage: StageNode }}
  fitView
/>

Theming

CSS Variables (recommended)

Consumer controls theme via --fp-* CSS custom properties. Components use var(--fp-*, fallback):

:root {
  --fp-color-primary: #7c6cf0;
  --fp-bg-primary: #1e1a2e;
  --fp-bg-secondary: #2a2540;
  --fp-bg-tertiary: #3a3455;
  --fp-text-primary: #f0e6d6;
  --fp-text-secondary: #b0a898;
  --fp-text-muted: #6b6b80;
  --fp-border: #3a3455;
  --fp-radius: 8px;
  --fp-font-sans: 'Inter', system-ui, sans-serif;
  --fp-font-mono: 'JetBrains Mono', monospace;
}

ThemeProvider

import { FootprintTheme, warmDark } from "footprint-explainable-ui";

<FootprintTheme tokens={warmDark}>
  <MyApp />
</FootprintTheme>

Built-in Presets

| Preset | Description | |---|---| | coolDark | Default — indigo/slate dark theme | | warmDark | Charcoal-purple with warm text | | warmLight | Cream/peach light theme | | coolLight | Light indigo theme |

Components Reference

Core Components

| Component | Description | |---|---| | ExplainableShell | All-in-one orchestrator with collapsible panels and responsive layout | | TimeTravelControls | Play/pause, prev/next, scrubber timeline | | MemoryPanel | Memory state + scope diff (composite right-panel view) | | NarrativePanel | Narrative trace with progressive reveal | | StoryNarrative | Rich rendering of structured NarrativeEntry[] | | NarrativeTrace | Collapsible stage groups with progressive reveal | | NarrativeLog | Simple timeline-style execution log | | ScopeDiff | Side-by-side scope changes (added/changed/removed) | | ResultPanel | Final pipeline output + console logs | | MemoryInspector | Accumulated memory state viewer | | GanttTimeline | Horizontal duration timeline (collapsible) | | SnapshotPanel | All-in-one inspector (scrubber + memory + narrative + Gantt) |

Flowchart Components (footprint-explainable-ui/flowchart)

| Export | Description | |---|---| | TracedFlowchartView | Self-contained flowchart with trace overlay and auto-fitView | | FlowchartView | Lower-level ReactFlow wrapper | | StageNode | Custom node with state-aware coloring, step badges, pulse rings | | specToReactFlow | Convert pipeline spec → ReactFlow nodes/edges with overlay | | SubflowBreadcrumb | Breadcrumb bar for subflow drill-down | | SubflowTree | Tree view of all subflows (used in shell's left panel) |

Adapters

| Export | Description | |---|---| | toVisualizationSnapshots | Convert FlowChartExecutor.getSnapshot() → StageSnapshot[] | | subflowResultToSnapshots | Convert subflow result → StageSnapshot[] | | createSnapshots | Build StageSnapshot[] from simple arrays (testing/custom data) |

Types

| Export | Description | |---|---| | PanelLabels | { topology?, details?, timeline? } — pill label customization | | DefaultExpanded | { topology?, details?, timeline? } — initial panel state | | StageSnapshot | Core snapshot type for all components | | NarrativeEntry | Structured narrative entry with type/depth/stageName |

Size Variants

All components accept a size prop: "compact", "default", or "detailed".

<GanttTimeline snapshots={snapshots} size="compact" />
<MemoryInspector snapshots={snapshots} size="detailed" />

Unstyled Mode

Strip all built-in styles for full CSS control. Components render semantic data-fp attributes:

<NarrativeTrace narrative={lines} unstyled className="my-narrative" />

[data-fp="narrative-header"] { font-weight: bold; }
[data-fp="narrative-step"] { padding-left: 2rem; }

License

MIT