@vertesia/fusion-ux 1.2.0 → 1.4.0-dev.20260614.160504Z

package/src/types.ts

@@ -13,74 +13,74 @@ import type React from 'react';
  * Root template structure for a fusion fragment
  */
 export interface FragmentTemplate {
-  /** Optional title displayed at the top */
-  title?: string;
-  /** Type of entity being displayed - helps with context */
-  entityType?: 'fund' | 'scenario' | 'portfolio' | 'transaction' | 'custom';
-  /** Sections containing fields */
-  sections: SectionTemplate[];
-  /** Optional footer text */
-  footer?: string;
+    /** Optional title displayed at the top */
+    title?: string;
+    /** Type of entity being displayed - helps with context */
+    entityType?: 'fund' | 'scenario' | 'portfolio' | 'transaction' | 'custom';
+    /** Sections containing fields */
+    sections: SectionTemplate[];
+    /** Optional footer text */
+    footer?: string;
 }
 
 /**
  * A section within the fragment, containing related fields, a table, or a chart
  */
 export interface SectionTemplate {
-  /** Section title/header */
-  title: string;
-  /** Layout mode for the fields */
-  layout?: 'grid-2' | 'grid-3' | 'grid-4' | 'list' | 'table' | 'chart';
-  /** Whether the section is initially collapsed */
-  collapsed?: boolean;
-  /** Fields in this section (for grid/list layouts) */
-  fields?: FieldTemplate[];
-  /** Table columns (for table layout) */
-  columns?: ColumnTemplate[];
-  /** Data key for table rows - points to an array in data */
-  dataKey?: string;
-  /** Chart specification (for chart layout) */
-  chart?: ChartTemplate;
+    /** Section title/header */
+    title: string;
+    /** Layout mode for the fields */
+    layout?: 'grid-2' | 'grid-3' | 'grid-4' | 'list' | 'table' | 'chart';
+    /** Whether the section is initially collapsed */
+    collapsed?: boolean;
+    /** Fields in this section (for grid/list layouts) */
+    fields?: FieldTemplate[];
+    /** Table columns (for table layout) */
+    columns?: ColumnTemplate[];
+    /** Data key for table rows - points to an array in data */
+    dataKey?: string;
+    /** Chart specification (for chart layout) */
+    chart?: ChartTemplate;
 }
 
 /**
  * A column definition for table layout
  */
 export interface ColumnTemplate {
-  /** Column header text */
-  header: string;
-  /** Key to look up in each row object */
-  key: string;
-  /** Display format */
-  format?: 'text' | 'number' | 'currency' | 'percent' | 'date' | 'boolean';
-  /** Column width (optional, e.g., '100px', '20%') */
-  width?: string;
-  /** Text alignment */
-  align?: 'left' | 'center' | 'right';
-  /** Currency code for currency format */
-  currency?: string;
-  /** Number of decimal places */
-  decimals?: number;
-  /** Highlight based on value (function key in data or static) */
-  highlight?: 'success' | 'warning' | 'error' | 'info';
+    /** Column header text */
+    header: string;
+    /** Key to look up in each row object */
+    key: string;
+    /** Display format */
+    format?: 'text' | 'number' | 'currency' | 'percent' | 'date' | 'boolean';
+    /** Column width (optional, e.g., '100px', '20%') */
+    width?: string;
+    /** Text alignment */
+    align?: 'left' | 'center' | 'right';
+    /** Currency code for currency format */
+    currency?: string;
+    /** Number of decimal places */
+    decimals?: number;
+    /** Highlight based on value (function key in data or static) */
+    highlight?: 'success' | 'warning' | 'error' | 'info';
 }
 
 /**
  * Chart specification for chart layout (Vega-Lite based)
  */
 export interface ChartTemplate {
-  /** Chart title (displayed above the chart) */
-  title?: string;
-  /** Chart description */
-  description?: string;
-  /** Vega-Lite specification */
-  spec: VegaLiteSpec;
-  /** Chart height in pixels */
-  height?: number;
-  /** Chart width in pixels (defaults to container width) */
-  width?: number;
-  /** Data key - if provided, data from this key replaces spec.data.values */
-  dataKey?: string;
+    /** Chart title (displayed above the chart) */
+    title?: string;
+    /** Chart description */
+    description?: string;
+    /** Vega-Lite specification */
+    spec: VegaLiteSpec;
+    /** Chart height in pixels */
+    height?: number;
+    /** Chart width in pixels (defaults to container width) */
+    width?: number;
+    /** Data key - if provided, data from this key replaces spec.data.values */
+    dataKey?: string;
 }
 
 /**
@@ -88,67 +88,67 @@ export interface ChartTemplate {
  * Full spec: https://vega.github.io/vega-lite/docs/spec.html
  */
 export interface VegaLiteSpec {
-  /** Schema URL (optional) */
-  $schema?: string;
-  /** Inline data or data source */
-  data?: {
-    /** Inline data values */
-    values?: Record<string, unknown>[];
-    /** URL to fetch data from */
-    url?: string;
-    /** Data format */
-    format?: { type?: 'json' | 'csv' | 'tsv' };
-  };
-  /** Mark type (bar, line, point, area, etc.) */
-  mark?: string | { type: string; [key: string]: unknown };
-  /** Encoding channels (x, y, color, size, etc.) */
-  encoding?: Record<string, unknown>;
-  /** Vertical concatenation */
-  vconcat?: VegaLiteSpec[];
-  /** Horizontal concatenation */
-  hconcat?: VegaLiteSpec[];
-  /** Layer multiple marks */
-  layer?: VegaLiteSpec[];
-  /** Transform operations */
-  transform?: Record<string, unknown>[];
-  /** Interactive parameters */
-  params?: Record<string, unknown>[];
-  /** Chart configuration */
-  config?: Record<string, unknown>;
-  /** Allow additional Vega-Lite properties */
-  [key: string]: unknown;
+    /** Schema URL (optional) */
+    $schema?: string;
+    /** Inline data or data source */
+    data?: {
+        /** Inline data values */
+        values?: Record<string, unknown>[];
+        /** URL to fetch data from */
+        url?: string;
+        /** Data format */
+        format?: { type?: 'json' | 'csv' | 'tsv' };
+    };
+    /** Mark type (bar, line, point, area, etc.) */
+    mark?: string | { type: string; [key: string]: unknown };
+    /** Encoding channels (x, y, color, size, etc.) */
+    encoding?: Record<string, unknown>;
+    /** Vertical concatenation */
+    vconcat?: VegaLiteSpec[];
+    /** Horizontal concatenation */
+    hconcat?: VegaLiteSpec[];
+    /** Layer multiple marks */
+    layer?: VegaLiteSpec[];
+    /** Transform operations */
+    transform?: Record<string, unknown>[];
+    /** Interactive parameters */
+    params?: Record<string, unknown>[];
+    /** Chart configuration */
+    config?: Record<string, unknown>;
+    /** Allow additional Vega-Lite properties */
+    [key: string]: unknown;
 }
 
 /**
  * A single field definition
  */
 export interface FieldTemplate {
-  /** Display label for the field */
-  label: string;
-  /** Key to look up in data - REQUIRED */
-  key: string;
-  /** Display format */
-  format?: 'text' | 'number' | 'currency' | 'percent' | 'date' | 'boolean';
-  /** Unit to display after value (e.g., "years", "USD") */
-  unit?: string;
-  /** Whether this field is editable */
-  editable?: boolean;
-  /** Input type when editing */
-  inputType?: 'text' | 'number' | 'date' | 'select' | 'checkbox';
-  /** Options for select input type */
-  options?: Array<{ label: string; value: string }>;
-  /** Min value for number inputs */
-  min?: number;
-  /** Max value for number inputs */
-  max?: number;
-  /** Visual highlight style */
-  highlight?: 'success' | 'warning' | 'error' | 'info';
-  /** Tooltip text on hover */
-  tooltip?: string;
-  /** Number of decimal places for number format */
-  decimals?: number;
-  /** Currency code for currency format */
-  currency?: string;
+    /** Display label for the field */
+    label: string;
+    /** Key to look up in data - REQUIRED */
+    key: string;
+    /** Display format */
+    format?: 'text' | 'number' | 'currency' | 'percent' | 'date' | 'boolean';
+    /** Unit to display after value (e.g., "years", "USD") */
+    unit?: string;
+    /** Whether this field is editable */
+    editable?: boolean;
+    /** Input type when editing */
+    inputType?: 'text' | 'number' | 'date' | 'select' | 'checkbox';
+    /** Options for select input type */
+    options?: Array<{ label: string; value: string }>;
+    /** Min value for number inputs */
+    min?: number;
+    /** Max value for number inputs */
+    max?: number;
+    /** Visual highlight style */
+    highlight?: 'success' | 'warning' | 'error' | 'info';
+    /** Tooltip text on hover */
+    tooltip?: string;
+    /** Number of decimal places for number format */
+    decimals?: number;
+    /** Currency code for currency format */
+    currency?: string;
 }
 
 // ============ Validation Types ============
@@ -157,22 +157,22 @@ export interface FieldTemplate {
  * Result of template validation
  */
 export interface ValidationResult {
-  /** Whether the template is valid */
-  valid: boolean;
-  /** List of validation errors */
-  errors: ValidationError[];
+    /** Whether the template is valid */
+    valid: boolean;
+    /** List of validation errors */
+    errors: ValidationError[];
 }
 
 /**
  * A single validation error with path and suggestion
  */
 export interface ValidationError {
-  /** JSON path to the error (e.g., "sections[0].fields[2].key") */
-  path: string;
-  /** Human-readable error message */
-  message: string;
-  /** Suggested fix (for model feedback) */
-  suggestion?: string;
+    /** JSON path to the error (e.g., "sections[0].fields[2].key") */
+    path: string;
+    /** Human-readable error message */
+    message: string;
+    /** Suggested fix (for model feedback) */
+    suggestion?: string;
 }
 
 // ============ Component Props ============
@@ -181,48 +181,48 @@ export interface ValidationError {
  * Props for the main FusionFragmentRenderer component
  */
 export interface FusionFragmentRendererProps {
-  /** The template structure (from model) */
-  template: FragmentTemplate;
-  /** Actual data values to display */
-  data: Record<string, unknown>;
-  /** Callback for field updates (direct mode) */
-  onUpdate?: (key: string, value: unknown) => Promise<void>;
-  /** Agent mode configuration */
-  agentMode?: {
-    enabled: true;
-    /** Send message to conversation */
-    sendMessage: (message: string) => void;
-  };
-  /** CSS class name */
-  className?: string;
+    /** The template structure (from model) */
+    template: FragmentTemplate;
+    /** Actual data values to display */
+    data: Record<string, unknown>;
+    /** Callback for field updates (direct mode) */
+    onUpdate?: (key: string, value: unknown) => Promise<void>;
+    /** Agent mode configuration */
+    agentMode?: {
+        enabled: true;
+        /** Send message to conversation */
+        sendMessage: (message: string) => void;
+    };
+    /** CSS class name */
+    className?: string;
 }
 
 /**
  * Props for section renderer
  */
 export interface SectionRendererProps {
-  /** Section template */
-  section: SectionTemplate;
-  /** Data for fields */
-  data: Record<string, unknown>;
-  /** Update callback */
-  onUpdate?: (key: string, value: unknown) => Promise<void>;
-  /** Agent mode */
-  agentMode?: FusionFragmentRendererProps['agentMode'];
+    /** Section template */
+    section: SectionTemplate;
+    /** Data for fields */
+    data: Record<string, unknown>;
+    /** Update callback */
+    onUpdate?: (key: string, value: unknown) => Promise<void>;
+    /** Agent mode */
+    agentMode?: FusionFragmentRendererProps['agentMode'];
 }
 
 /**
  * Props for field renderer
  */
 export interface FieldRendererProps {
-  /** Field template */
-  field: FieldTemplate;
-  /** Field value from data */
-  value: unknown;
-  /** Update callback */
-  onUpdate?: (value: unknown) => Promise<void>;
-  /** Agent mode */
-  agentMode?: FusionFragmentRendererProps['agentMode'];
+    /** Field template */
+    field: FieldTemplate;
+    /** Field value from data */
+    value: unknown;
+    /** Update callback */
+    onUpdate?: (value: unknown) => Promise<void>;
+    /** Agent mode */
+    agentMode?: FusionFragmentRendererProps['agentMode'];
 }
 
 // ============ Context Types ============
@@ -231,34 +231,34 @@ export interface FieldRendererProps {
  * Props for the injected chart component (matches @vertesia/ui VegaLiteChart)
  */
 export interface ChartComponentProps {
-  /** The chart specification in VegaLiteChartSpec format */
-  spec: {
-    library: 'vega-lite';
-    title?: string;
-    description?: string;
-    spec: Record<string, unknown>;
-    options?: {
-      height?: number;
+    /** The chart specification in VegaLiteChartSpec format */
+    spec: {
+        library: 'vega-lite';
+        title?: string;
+        description?: string;
+        spec: Record<string, unknown>;
+        options?: {
+            height?: number;
+        };
     };
-  };
-  /** Optional artifact run ID for resolving artifact: URLs */
-  artifactRunId?: string;
+    /** Optional artifact run ID for resolving artifact: URLs */
+    artifactRunId?: string;
 }
 
 /**
  * Context value for FusionFragment components
  */
 export interface FusionFragmentContextValue {
-  /** Data to display */
-  data: Record<string, unknown>;
-  /** Update callback */
-  onUpdate?: (key: string, value: unknown) => Promise<void>;
-  /** Send message to agent */
-  sendMessage?: (message: string) => void;
-  /** Optional chart component to render Vega-Lite charts (injected to avoid circular deps) */
-  ChartComponent?: React.ComponentType<ChartComponentProps>;
-  /** Optional artifact run ID for resolving artifact references */
-  artifactRunId?: string;
+    /** Data to display */
+    data: Record<string, unknown>;
+    /** Update callback */
+    onUpdate?: (key: string, value: unknown) => Promise<void>;
+    /** Send message to agent */
+    sendMessage?: (message: string) => void;
+    /** Optional chart component to render Vega-Lite charts (injected to avoid circular deps) */
+    ChartComponent?: React.ComponentType<ChartComponentProps>;
+    /** Optional artifact run ID for resolving artifact references */
+    artifactRunId?: string;
 }
 
 // ============ Tool Types ============
@@ -267,12 +267,12 @@ export interface FusionFragmentContextValue {
  * Input for validate_fusion_fragment tool
  */
 export interface ValidateFusionFragmentInput {
-  /** The template to validate */
-  template: FragmentTemplate;
-  /** Available data keys */
-  dataKeys: string[];
-  /** Optional sample data for preview rendering */
-  sampleData?: Record<string, unknown>;
-  /** Preview mode */
-  preview?: 'image' | 'text' | 'none';
+    /** The template to validate */
+    template: FragmentTemplate;
+    /** Available data keys */
+    dataKeys: string[];
+    /** Optional sample data for preview rendering */
+    sampleData?: Record<string, unknown>;
+    /** Preview mode */
+    preview?: 'image' | 'text' | 'none';
 }

package/src/validation/formatErrors.ts

@@ -10,22 +10,22 @@ import type { ValidationError } from '../types.js';
  * @returns Formatted error message
  */
 export function formatValidationErrors(errors: ValidationError[]): string {
-  if (errors.length === 0) {
-    return 'Template is valid.';
-  }
+    if (errors.length === 0) {
+        return 'Template is valid.';
+    }
 
-  const header = `Template validation failed with ${errors.length} error${errors.length > 1 ? 's' : ''}:\n`;
+    const header = `Template validation failed with ${errors.length} error${errors.length > 1 ? 's' : ''}:\n`;
 
-  const formattedErrors = errors.map((error, index) => {
-    let message = `${index + 1}. ${error.message}`;
-    message += `\n   Path: ${error.path}`;
-    if (error.suggestion) {
-      message += `\n   \u2192 ${error.suggestion}`;
-    }
-    return message;
-  });
+    const formattedErrors = errors.map((error, index) => {
+        let message = `${index + 1}. ${error.message}`;
+        message += `\n   Path: ${error.path}`;
+        if (error.suggestion) {
+            message += `\n   \u2192 ${error.suggestion}`;
+        }
+        return message;
+    });
 
-  return header + '\n' + formattedErrors.join('\n\n');
+    return `${header}\n${formattedErrors.join('\n\n')}`;
 }
 
 /**
@@ -35,39 +35,42 @@ export function formatValidationErrors(errors: ValidationError[]): string {
  * @returns Success message with preview
  */
 export function formatValidationSuccess(
-  template: { title?: string; sections: Array<{ title: string; fields: Array<{ label: string; key: string; format?: string }> }> },
-  dataKeys: string[]
+    template: {
+        title?: string;
+        sections: Array<{ title: string; fields: Array<{ label: string; key: string; format?: string }> }>;
+    },
+    dataKeys: string[],
 ): string {
-  const lines: string[] = ['Template valid. Preview:'];
-  lines.push('');
-
-  if (template.title) {
-    lines.push(`**${template.title}**`);
+    const lines: string[] = ['Template valid. Preview:'];
     lines.push('');
-  }
-
-  for (const section of template.sections) {
-    const fieldCount = section.fields.length;
-    lines.push(`[${section.title}] ${fieldCount} field${fieldCount > 1 ? 's' : ''}:`);
 
-    for (const field of section.fields) {
-      let fieldDesc = `- ${field.label} (${field.key}`;
-      if (field.format && field.format !== 'text') {
-        fieldDesc += `, ${field.format}`;
-      }
-      fieldDesc += ')';
-
-      // Check if key exists in data
-      if (!dataKeys.includes(field.key)) {
-        fieldDesc += ' \u26a0\ufe0f key not in data';
-      }
+    if (template.title) {
+        lines.push(`**${template.title}**`);
+        lines.push('');
+    }
 
-      lines.push(fieldDesc);
+    for (const section of template.sections) {
+        const fieldCount = section.fields.length;
+        lines.push(`[${section.title}] ${fieldCount} field${fieldCount > 1 ? 's' : ''}:`);
+
+        for (const field of section.fields) {
+            let fieldDesc = `- ${field.label} (${field.key}`;
+            if (field.format && field.format !== 'text') {
+                fieldDesc += `, ${field.format}`;
+            }
+            fieldDesc += ')';
+
+            // Check if key exists in data
+            if (!dataKeys.includes(field.key)) {
+                fieldDesc += ' \u26a0\ufe0f key not in data';
+            }
+
+            lines.push(fieldDesc);
+        }
+        lines.push('');
     }
-    lines.push('');
-  }
 
-  return lines.join('\n');
+    return lines.join('\n');
 }
 
 /**
@@ -76,53 +79,50 @@ export function formatValidationSuccess(
  * @param groupByPrefix - Whether to group keys by common prefix
  * @returns Formatted key list
  */
-export function formatAvailableKeys(
-  dataKeys: string[],
-  groupByPrefix: boolean = true
-): string {
-  if (dataKeys.length === 0) {
-    return 'No data keys available.';
-  }
-
-  if (!groupByPrefix || dataKeys.length <= 10) {
-    return `Available keys: ${dataKeys.join(', ')}`;
-  }
-
-  // Group by prefix (e.g., fund.name, fund.type -> fund.*)
-  const groups = new Map<string, string[]>();
-
-  for (const key of dataKeys) {
-    const dotIndex = key.indexOf('.');
-    if (dotIndex > 0) {
-      const prefix = key.substring(0, dotIndex);
-      const rest = key.substring(dotIndex + 1);
-      const group = groups.get(prefix) || [];
-      group.push(rest);
-      groups.set(prefix, group);
-    } else {
-      const group = groups.get('') || [];
-      group.push(key);
-      groups.set('', group);
+export function formatAvailableKeys(dataKeys: string[], groupByPrefix: boolean = true): string {
+    if (dataKeys.length === 0) {
+        return 'No data keys available.';
     }
-  }
-
-  const lines: string[] = ['Available keys:'];
-
-  // Top-level keys first
-  const topLevel = groups.get('');
-  if (topLevel && topLevel.length > 0) {
-    lines.push(`  ${topLevel.join(', ')}`);
-  }
-
-  // Grouped keys
-  for (const [prefix, keys] of groups) {
-    if (prefix === '') continue;
-    if (keys.length <= 3) {
-      lines.push(`  ${prefix}: ${keys.join(', ')}`);
-    } else {
-      lines.push(`  ${prefix}: ${keys.slice(0, 3).join(', ')}, ... (${keys.length} total)`);
+
+    if (!groupByPrefix || dataKeys.length <= 10) {
+        return `Available keys: ${dataKeys.join(', ')}`;
+    }
+
+    // Group by prefix (e.g., fund.name, fund.type -> fund.*)
+    const groups = new Map<string, string[]>();
+
+    for (const key of dataKeys) {
+        const dotIndex = key.indexOf('.');
+        if (dotIndex > 0) {
+            const prefix = key.substring(0, dotIndex);
+            const rest = key.substring(dotIndex + 1);
+            const group = groups.get(prefix) || [];
+            group.push(rest);
+            groups.set(prefix, group);
+        } else {
+            const group = groups.get('') || [];
+            group.push(key);
+            groups.set('', group);
+        }
+    }
+
+    const lines: string[] = ['Available keys:'];
+
+    // Top-level keys first
+    const topLevel = groups.get('');
+    if (topLevel && topLevel.length > 0) {
+        lines.push(`  ${topLevel.join(', ')}`);
+    }
+
+    // Grouped keys
+    for (const [prefix, keys] of groups) {
+        if (prefix === '') continue;
+        if (keys.length <= 3) {
+            lines.push(`  ${prefix}: ${keys.join(', ')}`);
+        } else {
+            lines.push(`  ${prefix}: ${keys.slice(0, 3).join(', ')}, ... (${keys.length} total)`);
+        }
     }
-  }
 
-  return lines.join('\n');
+    return lines.join('\n');
 }