@vertesia/ui 0.24.0-dev.202601221707

package/src/env/index.ts

@@ -0,0 +1,126 @@
+// hook to initialize the environment and auth session
+// the main app must call this hook before rendering the page.
+
+import { AuthTokenPayload } from "@vertesia/common";
+
+export interface EnvProps {
+    name: string; // the app name
+    version: string,
+    sdkVersion?: string, // the @vertesia/ui package version
+    isLocalDev: boolean,
+    isDocker: boolean,
+    type: "production" | "staging" | "preview" | "development" | string,
+    endpoints: {
+        zeno: string,
+        studio: string,
+        sts: string, // Security Token Service endpoint
+    },
+    firebase?: {
+        apiKey: string,
+        authDomain: string,
+        projectId: string,
+        appId?: string,
+        providerType?: string,
+    },
+    datadog?: boolean,
+    logger?: {
+        info: (msg: string, ...args: any) => void,
+        warn: (msg: string, ...args: any) => void,
+        error: (msg: string, ...args: any) => void,
+        debug: (msg: string, ...args: any) => void,
+    }
+    onLogin?: (token: AuthTokenPayload) => void,
+    onLogout?: () => void,
+}
+
+export class VertesiaEnvironment implements Readonly<EnvProps> {
+
+    constructor(private _props?: EnvProps | undefined) {
+    }
+
+    init(props?: EnvProps) {
+        this._props = props;
+        return this;
+    }
+
+    private prop<K extends keyof EnvProps>(name: K): EnvProps[K] {
+        if (!this._props) {
+            throw new Error("VertesiaEnvironment was not initialized");
+        }
+        return this._props[name];
+    }
+
+    get version() {
+        return this.prop("version");
+    }
+
+    get sdkVersion() {
+        return this._props?.sdkVersion;
+    }
+
+    get name() {
+        return this.prop("name");
+    }
+
+    get type() {
+        return this.prop("type");
+    }
+
+    get isProd() {
+        return this.type === "production";
+    }
+
+    get isStable() {
+        return this.type === "production" || this.type === "preview" || this.type === "disaster-recovery";
+    }
+
+    get isDev() {
+        return !this.isStable;
+    }
+
+    get isPreview() {
+        return this.type === "preview";
+    }
+
+    get isLocalDev() {
+        return this.prop("isLocalDev");
+    }
+
+    get isDocker() {
+        return this.prop("isDocker");
+    }
+
+    get endpoints() {
+        return this.prop("endpoints");
+    }
+
+    get firebase() {
+        return this.prop("firebase");
+    }
+
+    get datadog() {
+        return this._props?.datadog ?? false;
+    }
+
+    get logger() {
+        return this._props?.logger ?? console
+    }
+
+    /**
+     * Callback to notify the host app when the user logs in.
+     */
+    onLogin(token: AuthTokenPayload) {
+        this._props?.onLogin?.(token);
+    }
+
+    /**
+     * Callback to notify the host app when the user logs out
+     */
+    onLogout() {
+        this._props?.onLogout?.();
+    }
+}
+
+const Env = new VertesiaEnvironment();
+
+export { Env };

package/src/features/activity-doc/ActivityDoc.tsx

@@ -0,0 +1,199 @@
+import { ActivityDefinition, ActivityPropertyDefinition, ActivityTypeDefinition } from "@vertesia/common";
+import clsx from "clsx";
+import { AnimatePresence, motion } from "motion/react";
+import React, { useMemo, useState } from "react";
+
+function Badge({ children, secondary = false }: { children: React.ReactNode, secondary?: boolean }) {
+    const className = secondary ? "bg-secondary text-primary" : "text-foreground bg-muted";
+    return <span className={className}>{children}</span>
+}
+
+/**
+ * Resolve nested array inner type
+ * @param innerType
+ */
+function resolveInnerType(innerType: ActivityTypeDefinition | undefined) {
+    if (!innerType) {
+        return undefined;
+    } else if (innerType.name === "array") {
+        return resolveInnerType(innerType.innerType);
+    } else {
+        return innerType;
+    }
+}
+
+interface PropertySignatureProps {
+    property: ActivityPropertyDefinition;
+}
+function PropertySignature({ property }: PropertySignatureProps) {
+    return (
+        <div className="flex items-center gap-x-2">
+            <div className="font-semibold text-gray-600">{property.name}</div>
+            {property.optional && <Badge>optional</Badge>}
+            <Badge>{property.type.value}</Badge>
+        </div>
+    )
+}
+interface ActivitiesDocProps {
+    activities: ActivityDefinition[];
+}
+export function ActivitiesDoc({ activities }: ActivitiesDocProps) {
+    return (
+        <div className='flex flex-col gap-y-4 divide-y divide-gray-200'>
+            {activities.map(activity => <ActivityDoc key={activity.name} activity={activity} />)}
+        </div>
+    )
+}
+
+interface ActivitySectionTitleProps {
+    children: React.ReactNode;
+    code?: string;
+}
+function ActivitySectionTitle({ code, children }: ActivitySectionTitleProps) {
+    return (
+        <div className="flex gap-2 items-center border-b border-b-gray-200 mb-2">
+            <div className='text-lg font-medium text-gray-900 py-2 '>{children}</div>
+            {code && <div><Badge>{code}</Badge></div>}
+        </div>
+    )
+}
+interface ActivityDocProps {
+    activity: ActivityDefinition;
+    headingRef?: React.RefObject<HTMLDivElement>;
+    headingClass?: string;
+}
+export function ActivityDoc({ activity, headingClass, headingRef }: ActivityDocProps) {
+    return (
+        <div className={headingClass} id={activity.name} ref={headingRef}>
+            <div className="text-xl font-semibold pt-8">{activity.title}</div>
+            <div className="pb-4"><Badge>{activity.name}</Badge></div>
+            {
+                activity.doc &&
+                <div className="text-gray-700 pb-2">{activity.doc}</div>
+            }
+
+            <div className="pb-4">
+                <ActivitySectionTitle code={activity.paramsType}>Parameters</ActivitySectionTitle>
+                <div className="divide-y divide-gray-100">
+                    {activity.params.map(prop =>
+                        <PropertyDetails key={prop.name} property={prop} />
+                    )}
+                </div>
+            </div>
+            <div className="pb-4">
+                <ActivitySectionTitle>Returns</ActivitySectionTitle>
+                <div>{activity.returnType ? activity.returnType.value : "void"}</div>
+            </div>
+
+        </div>
+    )
+}
+
+function PropertyDetails({ property, className }: { className?: string, property: ActivityPropertyDefinition }) {
+    const expandable = useMemo(() => {
+        const type = resolveInnerType(property.type.innerType) ?? property.type;
+        if (type.name === "object" && type.members) {
+            return <ObjectMembersPanel members={type.members} />
+        } else if (type.name === 'enum' && type.enum) {
+            return <EnumValuesPanel values={type.enum} />
+        } else {
+            return null;
+        }
+    }, [property.type.innerType]);
+    return (
+        <div className={clsx("py-2", className)}>
+            <PropertySignature property={property} />
+            {property.doc && <div className="text-gray-700 text-sm pt-2">
+                {property.doc}
+            </div>}
+            {expandable && <div className="my-2 overflow-hidden">
+                {expandable}
+            </div>
+            }
+        </div>
+    )
+}
+
+interface EnumValuesPanelProps {
+    values: string[] | number[];
+}
+function EnumValuesPanel({ values }: EnumValuesPanelProps) {
+    return <div className="flex flex-wrap items-center gap-2">{
+        values.map((v, i) => <Badge secondary key={i}>{v}</Badge>)
+    }</div>
+}
+
+function ObjectMembersPanel({ members }: { members: ActivityPropertyDefinition[] }) {
+    return <ExpandablePanel
+        className='rounded-md border border-gray-200'
+        button={(isOn) => (
+            <div className="px-4 py-2 flex items-center gap-x-2 text-sm font-medium hover:text-blue-600">
+                <ExpandIcon isOpen={isOn} />
+                {
+                    isOn ?
+                        <div>Hide child properties</div>
+                        :
+                        <div>Show child properties</div>
+                }
+            </div>
+        )}
+        body={<NestedPropertiesDetails properties={members} />} />
+}
+
+function NestedPropertiesDetails({ properties }: { properties: ActivityPropertyDefinition[] }) {
+    return (
+        <div className='border-l-2 border-l-blue-200 flex flex-col divide-y divide-gray-100 border-t border-t-gray-200'>
+            {properties.map(prop => <PropertyDetails key={prop.name} property={prop} className="px-4 py-2" />)}
+        </div>
+    )
+}
+
+interface ExpandablePanelProps {
+    isInitiallyOpen?: boolean;
+    className?: string;
+    button: (isOn: boolean) => React.ReactNode;
+    body: React.ReactNode | React.ReactNode[];
+}
+function ExpandablePanel({ button, body, className, isInitiallyOpen }: ExpandablePanelProps) {
+    const [isExpanded, setExpanded] = useState(isInitiallyOpen || false);
+    return (
+        <div className={clsx(isExpanded ? "block" : "inline-block", className)}>
+            <button className='p-0 m-0 bg-transparent' onClick={() => setExpanded(!isExpanded)}>
+                <AnimatePresence>
+                    {button(isExpanded)}
+                </AnimatePresence>
+            </button>
+            <AnimatePresence>
+                {
+                    isExpanded && <motion.div className='overflow-hidden'
+                        initial={{ height: 0, opacity: 0 }}
+                        animate={{ height: 'auto', opacity: 1 }}
+                        exit={{ height: 0, opacity: 0 }}
+                        transition={{ duration: 0.3, ease: 'easeOut' }}
+                    >
+                        {body}
+                    </motion.div>
+                }
+            </AnimatePresence>
+        </div>
+    )
+}
+
+interface ExpandIconProps {
+    isOpen: boolean;
+}
+function ExpandIcon({ isOpen }: ExpandIconProps) {
+    return (
+        <AnimatePresence propagate mode="wait">
+            <motion.div
+                className="font-mono font-semibold text-gray-400 text-lg"
+                key="closeIcon"
+                initial={{ rotate: 0 }}
+                animate={{ rotate: isOpen ? 45 : 0 }}
+                transition={{ duration: 0.2 }}
+            >
+                +
+            </motion.div>
+        </AnimatePresence>
+    )
+}

package/src/features/activity-doc/index.ts

@@ -0,0 +1 @@
+export * from "./ActivityDoc";

package/src/features/agent/CHART_INSTRUCTIONS.md

@@ -0,0 +1,228 @@
+# Chart Creation Instructions for AI Agents
+
+This document provides instructions for AI agents on how to create interactive charts that will be rendered in the UI.
+
+## Overview
+
+You can create charts by including a special markdown code block with the language `chart`. The UI will automatically detect and render these as interactive Recharts visualizations.
+
+## Basic Format
+
+```markdown
+\`\`\`chart
+{
+  "version": "1.0",
+  "library": "recharts",
+  "chart": "bar" | "line" | "composed",
+  "title": "Chart Title",
+  "description": "Optional description",
+  "data": [ /* array of data objects */ ],
+  "xKey": "fieldName",
+  "series": [ /* array of series configurations */ ],
+  "yAxis": { /* optional axis labels */ },
+  "options": { /* optional chart options */ }
+}
+\`\`\`
+```
+
+## Chart Types
+
+### 1. Bar Chart
+Used for comparing values across categories.
+
+```chart
+{
+  "version": "1.0",
+  "chart": "bar",
+  "title": "Revenue by Quarter",
+  "data": [
+    { "quarter": "Q1", "revenue": 100000 },
+    { "quarter": "Q2", "revenue": 150000 },
+    { "quarter": "Q3", "revenue": 120000 }
+  ],
+  "xKey": "quarter",
+  "series": [
+    { "key": "revenue", "label": "Revenue", "type": "bar" }
+  ]
+}
+```
+
+### 2. Line Chart
+Used for showing trends over time.
+
+```chart
+{
+  "version": "1.0",
+  "chart": "line",
+  "title": "Performance Over Time",
+  "data": [
+    { "period": "2024-Q1", "tvpi": 1.2, "dpi": 0.3 },
+    { "period": "2024-Q2", "tvpi": 1.5, "dpi": 0.5 },
+    { "period": "2024-Q3", "tvpi": 1.8, "dpi": 0.7 }
+  ],
+  "xKey": "period",
+  "series": [
+    { "key": "tvpi", "label": "TVPI", "color": "#4f46e5", "dot": false },
+    { "key": "dpi", "label": "DPI", "color": "#16a34a", "dot": false }
+  ],
+  "yAxis": {
+    "left": { "label": "Multiple (x)" }
+  }
+}
+```
+
+### 3. Composed Chart
+Used for mixing bar and line charts (e.g., bars for cashflows, line for net).
+
+```chart
+{
+  "version": "1.0",
+  "chart": "composed",
+  "title": "Cashflow Timeline",
+  "data": [
+    { "period": "2024-Q1", "calls": 1000000, "distributions": 500000, "netCashflow": -500000 },
+    { "period": "2024-Q2", "calls": 800000, "distributions": 1200000, "netCashflow": 400000 }
+  ],
+  "xKey": "period",
+  "series": [
+    { "key": "calls", "label": "Calls", "type": "bar", "color": "#ef4444" },
+    { "key": "distributions", "label": "Distributions", "type": "bar", "color": "#22c55e" },
+    { "key": "netCashflow", "label": "Net CF", "type": "line", "color": "#0ea5e9", "yAxisId": "right", "dot": false }
+  ],
+  "yAxis": {
+    "left": { "label": "Amount" },
+    "right": { "label": "Net" }
+  },
+  "options": {
+    "referenceZero": true
+  }
+}
+```
+
+## Series Configuration
+
+Each series can have:
+
+- `key`: (required) The field name in the data
+- `label`: Display name for the legend
+- `type`: "bar" or "line" (for composed charts)
+- `color`: Hex color code (e.g., "#4f46e5")
+- `yAxisId`: "left" (default) or "right" for dual Y-axis
+- `stackId`: Group bars for stacking
+- `dot`: true/false - show dots on line charts
+
+## Options
+
+- `stacked`: true/false - Stack bars in bar charts
+- `referenceZero`: true/false - Show a reference line at y=0
+- `collapsible`: true/false - Allow users to collapse the chart (default: true)
+- `collapseInitially`: true/false - Start in collapsed state
+
+## Number Formatting
+
+Numbers are automatically formatted:
+- 1,000 → 1K
+- 1,000,000 → 1M
+- 1,000,000,000 → 1B
+
+## Pre-built Chart Builders (TypeScript)
+
+If you're writing TypeScript code, you can use these helper functions:
+
+```typescript
+import {
+  buildCashflowComposedChart,
+  buildPerformanceLineChart,
+  buildScenarioComparisonBarChart,
+  toChartMarkdown
+} from '@vertesia/ui/features';
+
+// Example: Create a cashflow chart
+const chart = buildCashflowComposedChart({
+  title: 'Fund Cashflow',
+  rows: [
+    { period: '2024-Q1', calls: 1000000, distributions: 500000 },
+    { period: '2024-Q2', calls: 800000, distributions: 1200000 }
+  ]
+});
+
+// Convert to markdown
+const markdown = toChartMarkdown(chart);
+```
+
+### Available Builders
+
+1. `buildCashflowComposedChart` - Calls/Distributions + Net CF
+2. `buildPerformanceLineChart` - TVPI/DPI/RVPI J-curve
+3. `buildScenarioComparisonBarChart` - Side-by-side comparison
+4. `buildScenarioDeltaPercentChart` - % change visualization
+5. `buildTvpiOverlayChart` - TVPI comparison between scenarios
+6. `buildNavLineChart` - NAV over time
+
+## Best Practices
+
+1. **Use appropriate chart types**:
+   - Bar charts for comparisons
+   - Line charts for trends
+   - Composed charts for mixed metrics
+
+2. **Keep data concise**:
+   - Limit to 20-30 data points for readability
+   - Use aggregation for large datasets
+
+3. **Color consistency**:
+   - Use the default color palette for consistency
+   - Red (#ef4444) for negative/costs
+   - Green (#22c55e) for positive/gains
+   - Blue (#0ea5e9) for neutral metrics
+
+4. **Add context**:
+   - Always include a descriptive title
+   - Add a description when the chart needs explanation
+   - Use axis labels for clarity
+
+5. **Dual Y-axis**:
+   - Use when comparing metrics with different scales
+   - Example: Amount (left) vs Count (right)
+
+## Example: Complete Workflow
+
+When a user asks "Show me the fund performance":
+
+1. Fetch or calculate the data
+2. Format it as a chart spec
+3. Include it in your response:
+
+```markdown
+Here's the fund performance over time:
+
+\`\`\`chart
+{
+  "version": "1.0",
+  "chart": "line",
+  "title": "Fund Performance",
+  "data": [
+    { "period": "2024-Q1", "tvpi": 1.2 },
+    { "period": "2024-Q2", "tvpi": 1.5 }
+  ],
+  "xKey": "period",
+  "series": [
+    { "key": "tvpi", "label": "TVPI", "color": "#4f46e5" }
+  ]
+}
+\`\`\`
+
+The fund shows strong performance with TVPI increasing from 1.2x to 1.5x.
+```
+
+## Common Pitfalls
+
+❌ **Don't** include line breaks in the JSON
+❌ **Don't** use single quotes in JSON (use double quotes)
+❌ **Don't** forget to specify the chart type
+❌ **Don't** mix up xKey with data field names
+
+✅ **Do** validate your JSON before including it
+✅ **Do** include descriptive labels
+✅ **Do** test with sample data first
+✅ **Do** provide context around the chart