@vertesia/ui 0.24.0-dev.202601221707

package/src/features/agent/examples.ts

@@ -0,0 +1,321 @@
+/**
+ * Chart creation examples for testing and reference.
+ *
+ * These examples demonstrate how to use the chart functionality
+ * from both AI agents and TypeScript code.
+ */
+
+import {
+    buildCashflowComposedChart,
+    buildPerformanceLineChart,
+    buildScenarioComparisonBarChart,
+    buildScenarioDeltaPercentChart,
+    buildNavLineChart,
+    toChartMarkdown,
+} from './visualization';
+
+/**
+ * Example 1: Simple bar chart (markdown)
+ */
+export const exampleBarChartMarkdown = `
+Here's a comparison of revenue across quarters:
+
+\`\`\`chart
+{
+  "version": "1.0",
+  "chart": "bar",
+  "title": "Quarterly Revenue",
+  "description": "Revenue performance by quarter",
+  "data": [
+    { "quarter": "Q1 2024", "revenue": 125000 },
+    { "quarter": "Q2 2024", "revenue": 145000 },
+    { "quarter": "Q3 2024", "revenue": 160000 },
+    { "quarter": "Q4 2024", "revenue": 180000 }
+  ],
+  "xKey": "quarter",
+  "series": [
+    {
+      "key": "revenue",
+      "label": "Revenue",
+      "type": "bar",
+      "color": "#4f46e5"
+    }
+  ],
+  "yAxis": {
+    "left": { "label": "Amount ($)" }
+  }
+}
+\`\`\`
+
+Revenue shows consistent growth throughout 2024.
+`;
+
+/**
+ * Example 2: Line chart with multiple series (markdown)
+ */
+export const exampleLineChartMarkdown = `
+Here's the fund performance over time:
+
+\`\`\`chart
+{
+  "version": "1.0",
+  "chart": "line",
+  "title": "Fund Performance Metrics",
+  "description": "TVPI, DPI, and RVPI over time",
+  "data": [
+    { "period": "2024-Q1", "tvpi": 1.2, "dpi": 0.3, "rvpi": 0.9 },
+    { "period": "2024-Q2", "tvpi": 1.4, "dpi": 0.5, "rvpi": 0.9 },
+    { "period": "2024-Q3", "tvpi": 1.6, "dpi": 0.7, "rvpi": 0.9 },
+    { "period": "2024-Q4", "tvpi": 1.8, "dpi": 0.9, "rvpi": 0.9 }
+  ],
+  "xKey": "period",
+  "series": [
+    {
+      "key": "tvpi",
+      "label": "TVPI",
+      "type": "line",
+      "color": "#4f46e5",
+      "dot": false
+    },
+    {
+      "key": "dpi",
+      "label": "DPI",
+      "type": "line",
+      "color": "#16a34a",
+      "dot": false
+    },
+    {
+      "key": "rvpi",
+      "label": "RVPI",
+      "type": "line",
+      "color": "#f59e0b",
+      "dot": false
+    }
+  ],
+  "yAxis": {
+    "left": { "label": "Multiple (x)" }
+  },
+  "options": {
+    "referenceZero": false
+  }
+}
+\`\`\`
+
+The fund shows strong performance with TVPI growing to 1.8x.
+`;
+
+/**
+ * Example 3: Composed chart with dual Y-axis (markdown)
+ */
+export const exampleComposedChartMarkdown = `
+Here's the cashflow analysis:
+
+\`\`\`chart
+{
+  "version": "1.0",
+  "chart": "composed",
+  "title": "Fund Cashflow Timeline",
+  "description": "Capital calls, distributions, and net cashflow",
+  "data": [
+    { "period": "2024-Q1", "calls": 2000000, "distributions": 500000, "net": -1500000 },
+    { "period": "2024-Q2", "calls": 1500000, "distributions": 800000, "net": -700000 },
+    { "period": "2024-Q3", "calls": 1000000, "distributions": 1200000, "net": 200000 },
+    { "period": "2024-Q4", "calls": 500000, "distributions": 1800000, "net": 1300000 }
+  ],
+  "xKey": "period",
+  "series": [
+    {
+      "key": "calls",
+      "label": "Capital Calls",
+      "type": "bar",
+      "color": "#ef4444"
+    },
+    {
+      "key": "distributions",
+      "label": "Distributions",
+      "type": "bar",
+      "color": "#22c55e"
+    },
+    {
+      "key": "net",
+      "label": "Net Cashflow",
+      "type": "line",
+      "color": "#0ea5e9",
+      "yAxisId": "right",
+      "dot": false
+    }
+  ],
+  "yAxis": {
+    "left": { "label": "Amount ($)" },
+    "right": { "label": "Net CF ($)" }
+  },
+  "options": {
+    "referenceZero": true
+  }
+}
+\`\`\`
+
+The fund transitions from net negative to net positive cashflow in Q3.
+`;
+
+/**
+ * Example 4: Using TypeScript builders
+ */
+export function generateCashflowChart() {
+    const chart = buildCashflowComposedChart({
+        title: 'Fund Cashflow Analysis',
+        description: 'Quarterly cashflows with net overlay',
+        rows: [
+            { period: '2024-Q1', calls: 2000000, distributions: 500000 },
+            { period: '2024-Q2', calls: 1500000, distributions: 800000 },
+            { period: '2024-Q3', calls: 1000000, distributions: 1200000 },
+            { period: '2024-Q4', calls: 500000, distributions: 1800000 },
+        ],
+        collapseInitially: false,
+    });
+
+    return toChartMarkdown(chart);
+}
+
+/**
+ * Example 5: Performance chart with TypeScript
+ */
+export function generatePerformanceChart() {
+    const chart = buildPerformanceLineChart({
+        title: 'Fund Performance',
+        description: 'TVPI, DPI, and RVPI over time',
+        rows: [
+            { period: '2024-Q1', tvpi: 1.2, dpi: 0.3, rvpi: 0.9 },
+            { period: '2024-Q2', tvpi: 1.4, dpi: 0.5, rvpi: 0.9 },
+            { period: '2024-Q3', tvpi: 1.6, dpi: 0.7, rvpi: 0.9 },
+            { period: '2024-Q4', tvpi: 1.8, dpi: 0.9, rvpi: 0.9 },
+        ],
+    });
+
+    return toChartMarkdown(chart);
+}
+
+/**
+ * Example 6: Scenario comparison
+ */
+export function generateScenarioComparisonChart() {
+    const chart = buildScenarioComparisonBarChart({
+        title: 'Base vs Optimistic Scenario',
+        leftLabel: 'Base Case',
+        rightLabel: 'Optimistic Case',
+        metrics: [
+            { label: 'Final TVPI', left: 2.5, right: 3.2 },
+            { label: 'IRR (%)', left: 18, right: 25 },
+            { label: 'Total Distributions ($M)', left: 125, right: 160 },
+        ],
+        description: 'Comparison of key metrics across scenarios',
+    });
+
+    return toChartMarkdown(chart);
+}
+
+/**
+ * Example 7: Delta percentage chart
+ */
+export function generateDeltaChart() {
+    const chart = buildScenarioDeltaPercentChart({
+        title: 'Performance vs Plan',
+        metrics: [
+            { label: 'Revenue', left: 1000000, right: 1200000 },
+            { label: 'EBITDA', left: 250000, right: 320000 },
+            { label: 'Net Income', left: 150000, right: 180000 },
+        ],
+        description: 'Percentage change from plan',
+    });
+
+    return toChartMarkdown(chart);
+}
+
+/**
+ * Example 8: NAV timeline
+ */
+export function generateNavChart() {
+    const chart = buildNavLineChart({
+        title: 'Fund NAV Over Time',
+        description: 'Net Asset Value progression',
+        rows: [
+            { period: '2024-Q1', nav: 10000000 },
+            { period: '2024-Q2', nav: 12000000 },
+            { period: '2024-Q3', nav: 15000000 },
+            { period: '2024-Q4', nav: 18000000 },
+        ],
+    });
+
+    return toChartMarkdown(chart);
+}
+
+/**
+ * Example 9: Complete agent response with chart
+ */
+export const exampleAgentResponseWithChart = `
+I've analyzed the fund performance for Q1-Q4 2024. Here are the key findings:
+
+## Performance Summary
+
+- **Final TVPI:** 1.8x
+- **Final DPI:** 0.9x
+- **Net Cashflow:** Positive since Q3
+
+## Visual Analysis
+
+${generatePerformanceChart()}
+
+## Cashflow Breakdown
+
+${generateCashflowChart()}
+
+## Recommendations
+
+1. The fund is performing well above industry benchmarks
+2. Cashflow turned positive in Q3, indicating maturity
+3. Consider planning distributions for Q1 2025
+
+Would you like me to run a Monte Carlo simulation to project future scenarios?
+`;
+
+/**
+ * Example 10: Error handling example
+ */
+export const exampleInvalidChart = `
+This will fall back to a code block because the JSON is invalid:
+
+\`\`\`chart
+{
+  "chart": "bar",
+  // Missing required fields
+  "title": "Invalid Chart"
+}
+\`\`\`
+
+The UI will render this as a regular code block.
+`;
+
+/**
+ * Test data generator for interactive testing
+ */
+export function generateTestData(periods: number) {
+    const data = [];
+
+    for (let i = 0; i < periods; i++) {
+        const quarter = Math.floor(i / 3) + 1;
+        const year = 2024 + Math.floor(i / 4);
+        const period = `${year}-Q${quarter}`;
+
+        data.push({
+            period,
+            tvpi: 1.0 + (i * 0.15) + (Math.random() * 0.1),
+            dpi: 0.2 + (i * 0.08) + (Math.random() * 0.05),
+            rvpi: 0.8 + (i * 0.07) + (Math.random() * 0.05),
+            calls: Math.floor(500000 + Math.random() * 1500000),
+            distributions: Math.floor(300000 + Math.random() * 2000000),
+            nav: Math.floor(5000000 + (i * 1000000) + (Math.random() * 500000)),
+        });
+    }
+
+    return data;
+}

package/src/features/agent/index.ts

@@ -0,0 +1,4 @@
+export * from "./chat";
+export * from "./PayloadBuilder";
+export * from "./visualization";
+export * from "./createChartTool";

package/src/features/agent/visualization.ts

@@ -0,0 +1,227 @@
+/**
+ * Visualization helpers for tools to emit chart specs that the UI can render.
+ *
+ * Format: ChartSpec v1 rendered by AgentChart component
+ */
+
+import type { AgentChartSpec } from './chat/AgentChart';
+
+export type ChartSpecV1 = AgentChartSpec;
+
+/**
+ * Build a side-by-side bar chart comparing two scenarios across numeric metrics.
+ */
+export function buildScenarioComparisonBarChart(params: {
+    title?: string;
+    leftLabel: string;
+    rightLabel: string;
+    metrics: Array<{
+        label: string;
+        left: number;
+        right: number;
+    }>;
+    description?: string;
+    collapseInitially?: boolean;
+}): ChartSpecV1 {
+    const { title, leftLabel, rightLabel, metrics, description, collapseInitially } = params;
+    const data = metrics.map((m) => ({ label: m.label, left: m.left, right: m.right }));
+    const spec: ChartSpecV1 = {
+        version: '1.0',
+        library: 'recharts',
+        chart: 'bar',
+        title: title || 'Scenario Comparison',
+        description,
+        data,
+        xKey: 'label',
+        series: [
+            { key: 'left', label: leftLabel, type: 'bar' },
+            { key: 'right', label: rightLabel, type: 'bar' },
+        ],
+        yAxis: { left: { label: 'Value' } },
+        options: { stacked: false, referenceZero: false, collapseInitially },
+    };
+    return spec;
+}
+
+/**
+ * Build a delta percentage bar chart to visualize changes between scenarios.
+ */
+export function buildScenarioDeltaPercentChart(params: {
+    title?: string;
+    metrics: Array<{
+        label: string;
+        left: number;
+        right: number;
+    }>;
+    description?: string;
+    collapseInitially?: boolean;
+}): ChartSpecV1 {
+    const { title, metrics, description, collapseInitially } = params;
+    const data = metrics.map((m) => ({
+        label: m.label,
+        deltaPct: m.left !== 0 ? ((m.right - m.left) / m.left) * 100 : 0,
+    }));
+    const spec: ChartSpecV1 = {
+        version: '1.0',
+        library: 'recharts',
+        chart: 'bar',
+        title: title || 'Change vs. Baseline (%)',
+        description,
+        data,
+        xKey: 'label',
+        series: [
+            { key: 'deltaPct', label: '% Change', type: 'bar' },
+        ],
+        yAxis: { left: { label: '% Change' } },
+        options: { stacked: false, referenceZero: true, collapseInitially },
+    };
+    return spec;
+}
+
+/**
+ * Helper to wrap a chart spec in a markdown code fence the UI will render.
+ */
+export function toChartMarkdown(spec: ChartSpecV1): string {
+    const json = JSON.stringify(spec, null, 2);
+    return [
+        '```chart',
+        json,
+        '```',
+    ].join('\n');
+}
+
+/**
+ * Build a cashflow composed chart (Calls/Distributions bars + Net Cashflow line)
+ */
+export function buildCashflowComposedChart(params: {
+    title?: string;
+    description?: string;
+    rows: Array<{
+        period: string; // e.g. '2024-Q1' or '2024'
+        calls: number;
+        distributions: number;
+        netCashflow?: number;
+    }>;
+    collapseInitially?: boolean;
+}): ChartSpecV1 {
+    const { title, description, rows, collapseInitially } = params;
+    const spec: ChartSpecV1 = {
+        version: '1.0',
+        library: 'recharts',
+        chart: 'composed',
+        title: title || 'Cashflow Timeline',
+        description,
+        data: rows.map((r) => ({
+            period: r.period,
+            calls: r.calls,
+            distributions: r.distributions,
+            netCashflow: r.netCashflow ?? (r.distributions - r.calls),
+        })),
+        xKey: 'period',
+        series: [
+            { key: 'calls', label: 'Calls', type: 'bar', color: '#ef4444' },
+            { key: 'distributions', label: 'Distributions', type: 'bar', color: '#22c55e' },
+            { key: 'netCashflow', label: 'Net Cashflow', type: 'line', color: '#0ea5e9', yAxisId: 'right', dot: false },
+        ],
+        yAxis: { left: { label: 'Amount' }, right: { label: 'Net' } },
+        options: { stacked: false, referenceZero: true, collapseInitially },
+    };
+    return spec;
+}
+
+/**
+ * Build a multi-line performance chart (TVPI/DPI/RVPI)
+ */
+export function buildPerformanceLineChart(params: {
+    title?: string;
+    description?: string;
+    rows: Array<{
+        period: string;
+        tvpi?: number;
+        dpi?: number;
+        rvpi?: number;
+    }>;
+    collapseInitially?: boolean;
+}): ChartSpecV1 {
+    const { title, description, rows, collapseInitially } = params;
+    const data = rows.map((r) => ({
+        period: r.period,
+        tvpi: r.tvpi ?? null,
+        dpi: r.dpi ?? null,
+        rvpi: r.rvpi ?? null,
+    }));
+    const spec: ChartSpecV1 = {
+        version: '1.0',
+        library: 'recharts',
+        chart: 'line',
+        title: title || 'Performance (J‑Curve)',
+        description,
+        data,
+        xKey: 'period',
+        series: [
+            { key: 'tvpi', label: 'TVPI', type: 'line', color: '#4f46e5', dot: false },
+            { key: 'dpi', label: 'DPI', type: 'line', color: '#16a34a', dot: false },
+            { key: 'rvpi', label: 'RVPI', type: 'line', color: '#f59e0b', dot: false },
+        ],
+        yAxis: { left: { label: 'Multiple (x)' } },
+        options: { stacked: false, referenceZero: true, collapseInitially },
+    };
+    return spec;
+}
+
+/**
+ * Build a TVPI-only overlay chart (two series, e.g., left vs right scenario)
+ */
+export function buildTvpiOverlayChart(params: {
+    title?: string;
+    description?: string;
+    rows: Array<{ period: string; tvpi_left?: number; tvpi_right?: number }>;
+    leftLabel: string;
+    rightLabel: string;
+    collapseInitially?: boolean;
+}): ChartSpecV1 {
+    const { title, description, rows, leftLabel, rightLabel, collapseInitially } = params;
+    const spec: ChartSpecV1 = {
+        version: '1.0',
+        library: 'recharts',
+        chart: 'line',
+        title: title || 'TVPI Over Time',
+        description,
+        data: rows,
+        xKey: 'period',
+        series: [
+            { key: 'tvpi_left', label: `TVPI – ${leftLabel}`, type: 'line', color: '#4f46e5', dot: false },
+            { key: 'tvpi_right', label: `TVPI – ${rightLabel}`, type: 'line', color: '#6366f1', dot: false },
+        ],
+        yAxis: { left: { label: 'Multiple (x)' } },
+        options: { stacked: false, referenceZero: true, collapseInitially },
+    };
+    return spec;
+}
+
+/**
+ * Build a NAV over time line chart (single line, right or left axis)
+ */
+export function buildNavLineChart(params: {
+    title?: string;
+    description?: string;
+    rows: Array<{ period: string; nav: number }>;
+    collapseInitially?: boolean;
+}): ChartSpecV1 {
+    const { title, description, rows, collapseInitially } = params;
+    const spec: ChartSpecV1 = {
+        version: '1.0',
+        library: 'recharts',
+        chart: 'line',
+        title: title || 'NAV Over Time',
+        description,
+        data: rows.map(r => ({ period: r.period, nav: r.nav })),
+        xKey: 'period',
+        series: [
+            { key: 'nav', label: 'NAV', type: 'line', color: '#0ea5e9', dot: false },
+        ],
+        yAxis: { left: { label: 'NAV' } },
+        options: { stacked: false, referenceZero: true, collapseInitially },
+    };
+    return spec;
+}

package/src/features/errors/PanelErrorBoundary.tsx

@@ -0,0 +1,30 @@
+import { MessageBox } from '@vertesia/ui/core';
+import { VertesiaErrorBoundary } from './VertesiaErrorBoundary';
+import { ReactNode } from 'react';
+
+export function PanelErrorBoundary({ children }: { children: ReactNode }) {
+    return (
+        <VertesiaErrorBoundary fallback={PanelErrorFallback}>
+            {children}
+        </VertesiaErrorBoundary>
+    );
+}
+
+function PanelErrorFallback({ error }: { error?: Error }) {
+    return (
+        <MessageBox status="error" title="Sorry, something went wrong...">
+            <div className='mb-4'>
+                Our team has been notified and will be quickly working on resolving it.
+                If you&apos;d like to escalate or simply contact us, please email us at&nbsp;
+
+                <a className='text-info' href="mailto:support@vertesiahq.com">support@vertesiahq.com</a>.
+            </div>
+
+            {error?.message &&
+                <code className='w-full mt-4 text-sm text-muted break-words'>
+                    {error.message}
+                </code>
+            }
+        </MessageBox>
+    );
+}

package/src/features/errors/RowErrorBoundary.tsx

@@ -0,0 +1,28 @@
+import { VertesiaErrorBoundary } from "./VertesiaErrorBoundary";
+import { ReactNode } from "react";
+
+interface ErrorBoundaryProps {
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+
+export function RowErrorBoundary({ children }: ErrorBoundaryProps) {
+
+    return (
+        <VertesiaErrorBoundary fallback={RowErrorFallback}>
+            {children}
+        </VertesiaErrorBoundary>
+    )
+}
+
+function RowErrorFallback({ error }: { error?: Error }) {
+    return (
+        <tr>
+            <td colSpan={100}>
+                <span className="text-xs"> Cannot display row</span>
+                <br />
+                <span className="bg-gray-400">{error?.message}</span>
+            </td>
+        </tr>
+    )
+}

package/src/features/errors/VertesiaErrorBoundary.tsx

@@ -0,0 +1,28 @@
+import { ReactNode, ComponentType } from "react"
+import { ErrorBoundary } from "react-error-boundary";
+
+export interface ErrorFallbackComponentProps {
+    error: any;
+    resetErrorBoundary: (...args: any[]) => void;
+}
+export type ErrorBoundaryProps = {
+    children: ReactNode;
+    fallback: ComponentType<ErrorFallbackComponentProps>;
+};
+
+export function VertesiaErrorBoundary({ children, fallback }: ErrorBoundaryProps) {
+    if (ErrorBoundaryInstance) { // custom error boundary?
+        return <ErrorBoundaryInstance fallback={fallback}>{children}</ErrorBoundaryInstance>
+    } else {
+        return <ErrorBoundary FallbackComponent={fallback}>{children}</ErrorBoundary>
+    }
+}
+
+let ErrorBoundaryInstance: ComponentType<{
+    fallback: ComponentType<ErrorFallbackComponentProps>;
+    children: ReactNode;
+}> | null = null;
+
+export function setErrorBoundaryComponent(ErrorBoundaryComponent: ComponentType<ErrorBoundaryProps>) {
+    ErrorBoundaryInstance = ErrorBoundaryComponent;
+}

package/src/features/errors/WidgetErrorBoundary.tsx

@@ -0,0 +1,27 @@
+import { VertesiaErrorBoundary } from './VertesiaErrorBoundary';
+import { ReactNode } from 'react';
+
+export function WidgetErrorBoundary({ children }: { children: ReactNode }) {
+
+    return (
+        <VertesiaErrorBoundary fallback={WidgetErrorFallback}>
+            {children}
+        </VertesiaErrorBoundary>
+    )
+}
+
+function WidgetErrorFallback({ error }: { error?: Error }) {
+
+    console.log('WidgetError', error);
+
+    return (
+        <div className="text-sm">
+            Sorry, this area cannot be loaded or rendered.
+            {error?.message &&
+                <pre>
+                    {error.message}
+                </pre>
+            }
+        </div>
+    )
+}

package/src/features/errors/index.ts

@@ -0,0 +1,4 @@
+export * from "./VertesiaErrorBoundary";
+export * from "./PanelErrorBoundary";
+export * from "./RowErrorBoundary";
+export * from "./WidgetErrorBoundary";