API Reference

Veltix provides a comprehensive API for building custom dashboards and integrating with external systems.

Overview

The Veltix API includes:

Core API: Main dashboard and component APIs
Chart API: Chart-specific configuration and methods
Data API: Data source and transformation APIs
Theme API: Theme and styling APIs
Event API: Event handling and interaction APIs

Core API

Dashboard API


import { Dashboard, useDashboard } from '@veltix/core';
 
// Dashboard configuration
interface DashboardConfig {
  id: string;
  title: string;
  layout: LayoutConfig;
  components: ComponentConfig[];
  theme: ThemeConfig;
  dataSources: DataSourceConfig[];
}
 
// Dashboard hook
function DashboardComponent() {
  const {
    dashboard,
    addComponent,
    removeComponent,
    updateComponent,
    saveDashboard,
    loadDashboard
  } = useDashboard();
 
  return (
    <Dashboard
      config={dashboard}
      onComponentAdd={addComponent}
      onComponentRemove={removeComponent}
      onComponentUpdate={updateComponent}
    />
  );
}

Component API


import { Component, useComponent } from '@veltix/core';
 
// Component configuration
interface ComponentConfig {
  id: string;
  type: string;
  position: { x: number; y: number };
  size: { width: number; height: number };
  data: any;
  config: any;
  style: CSSProperties;
}
 
// Component hook
function ChartComponent({ id }) {
  const {
    component,
    updateData,
    updateConfig,
    updateStyle,
    resize,
    move
  } = useComponent(id);
 
  return (
    <Component
      config={component}
      onDataUpdate={updateData}
      onConfigUpdate={updateConfig}
      onStyleUpdate={updateStyle}
    />
  );
}

Chart API

Chart Configuration


import { BarChart, LineChart, PieChart } from '@veltix/charts';
 
// Common chart configuration
interface ChartConfig {
  data: any[];
  xField: string;
  yField: string;
  color?: string | string[];
  height?: number;
  width?: number;
  animation?: boolean;
  grid?: boolean;
  legend?: boolean;
  tooltip?: boolean;
}
 
// Bar chart
<BarChart
  data={data}
  xField="category"
  yField="value"
  color="#1890ff"
  height={300}
  animation={true}
  grid={true}
  legend={true}
  tooltip={true}
/>
 
// Line chart
<LineChart
  data={data}
  xField="date"
  yField="sales"
  smooth={true}
  area={false}
  markers={true}
/>
 
// Pie chart
<PieChart
  data={data}
  nameField="name"
  valueField="value"
  donut={true}
  explode={false}
  labels={true}
/>

Chart Methods


import { useChart } from '@veltix/charts';
 
function ChartWithMethods() {
  const {
    chart,
    setData,
    setConfig,
    resize,
    highlight,
    select,
    export
  } = useChart();
 
  // Update chart data
  const updateData = (newData) => {
    setData(newData);
  };
 
  // Export chart as image
  const exportChart = () => {
    export({
      format: 'png',
      width: 800,
      height: 600
    });
  };
 
  return (
    <BarChart
      ref={chart}
      data={data}
      onDataUpdate={updateData}
      onExport={exportChart}
    />
  );
}

Data API

Data Source API


import { useDataSource, DataSource } from '@veltix/data';
 
// Data source configuration
interface DataSourceConfig {
  id: string;
  type: 'static' | 'api' | 'database' | 'file' | 'websocket';
  config: any;
  refreshInterval?: number;
  transforms?: TransformConfig[];
}
 
// Data source hook
function DataComponent() {
  const {
    data,
    loading,
    error,
    refresh,
    subscribe,
    unsubscribe
  } = useDataSource('sales-data');
 
  return (
    <div>
      {loading && <div>Loading...</div>}
      {error && <div>Error: {error.message}</div>}
      {data && <BarChart data={data} />}
    </div>
  );
}

Data Transformation API


import { useDataTransform } from '@veltix/data';
 
// Transformation configuration
interface TransformConfig {
  type: 'filter' | 'sort' | 'aggregate' | 'map' | 'custom';
  config: any;
}
 
function TransformedData() {
  const { transformedData, addTransform, removeTransform } = useDataTransform(
    originalData,
    transforms
  );
 
  // Add filter transform
  const addFilter = () => {
    addTransform({
      type: 'filter',
      config: {
        field: 'region',
        operator: 'equals',
        value: 'North'
      }
    });
  };
 
  return (
    <BarChart data={transformedData} />
  );
}

Theme API

Theme Configuration


import { useTheme, ThemeProvider } from '@veltix/ui';
 
// Theme configuration
interface ThemeConfig {
  name: string;
  colors: ColorPalette;
  typography: TypographyConfig;
  spacing: SpacingConfig;
  borderRadius: BorderRadiusConfig;
  shadows: ShadowConfig;
}
 
// Theme hook
function ThemedComponent() {
  const {
    theme,
    setTheme,
    isDark,
    colors,
    typography
  } = useTheme();
 
  return (
    <div style={{ backgroundColor: colors.background.primary }}>
      <h1 style={{ color: colors.text.primary }}>
        Themed Content
      </h1>
    </div>
  );
}
 
// Theme provider
function App() {
  return (
    <ThemeProvider
      defaultTheme="light"
      themes={['light', 'dark', 'corporate']}
    >
      <Dashboard />
    </ThemeProvider>
  );
}

Color API


import { useColors, generateColorPalette } from '@veltix/ui';
 
function ColorComponent() {
  const { primary, secondary, accent } = useColors();
 
  // Generate color palette
  const customPalette = generateColorPalette('#1890ff', {
    steps: 10,
    format: 'hex'
  });
 
  return (
    <div style={{ backgroundColor: primary[500] }}>
      Custom colored content
    </div>
  );
}

Event API

Event Handling


import { useEvents, EventEmitter } from '@veltix/core';
 
// Event configuration
interface EventConfig {
  type: string;
  target: string;
  action: string;
  data?: any;
}
 
// Event hook
function EventComponent() {
  const { emit, subscribe, unsubscribe } = useEvents();
 
  // Subscribe to events
  useEffect(() => {
    const handleClick = (data) => {
      console.log('Component clicked:', data);
    };
 
    subscribe('component:click', handleClick);
 
    return () => {
      unsubscribe('component:click', handleClick);
    };
  }, []);
 
  // Emit events
  const handleClick = () => {
    emit('component:click', {
      componentId: 'chart-1',
      data: { x: 100, y: 200 }
    });
  };
 
  return (
    <button onClick={handleClick}>
      Click me
    </button>
  );
}

Interaction API


import { useInteraction } from '@veltix/core';
 
function InteractiveChart() {
  const {
    onHover,
    onClick,
    onSelect,
    onZoom,
    onPan
  } = useInteraction();
 
  return (
    <BarChart
      data={data}
      onHover={onHover}
      onClick={onClick}
      onSelect={onSelect}
      onZoom={onZoom}
      onPan={onPan}
    />
  );
}

Layout API

Layout Management


import { useLayout, LayoutManager } from '@veltix/core';
 
// Layout configuration
interface LayoutConfig {
  type: 'free' | 'grid' | 'flex';
  grid?: GridConfig;
  flex?: FlexConfig;
  components: ComponentLayout[];
}
 
function LayoutComponent() {
  const {
    layout,
    addComponent,
    removeComponent,
    moveComponent,
    resizeComponent,
    snapToGrid
  } = useLayout();
 
  return (
    <LayoutManager
      layout={layout}
      onComponentAdd={addComponent}
      onComponentRemove={removeComponent}
      onComponentMove={moveComponent}
      onComponentResize={resizeComponent}
    />
  );
}

Grid API


import { useGrid } from '@veltix/core';
 
function GridComponent() {
  const {
    grid,
    snapToGrid,
    enableGrid,
    disableGrid,
    setGridSize
  } = useGrid({
    size: 20,
    enabled: true,
    snapThreshold: 10
  });
 
  return (
    <div>
      <button onClick={() => enableGrid()}>Enable Grid</button>
      <button onClick={() => disableGrid()}>Disable Grid</button>
      <input
        type="range"
        min="10"
        max="50"
        onChange={(e) => setGridSize(parseInt(e.target.value))}
      />
    </div>
  );
}

Storage API

Dashboard Storage


import { useStorage } from '@veltix/core';
 
function StorageComponent() {
  const {
    save,
    load,
    list,
    delete: deleteDashboard,
    export: exportDashboard,
    import: importDashboard
  } = useStorage();
 
  // Save dashboard
  const saveDashboard = async (dashboard) => {
    await save('my-dashboard', dashboard);
  };
 
  // Load dashboard
  const loadDashboard = async () => {
    const dashboard = await load('my-dashboard');
    return dashboard;
  };
 
  // List dashboards
  const listDashboards = async () => {
    const dashboards = await list();
    return dashboards;
  };
 
  return (
    <div>
      <button onClick={() => saveDashboard(dashboard)}>
        Save Dashboard
      </button>
      <button onClick={() => loadDashboard()}>
        Load Dashboard
      </button>
    </div>
  );
}

Export/Import API


import { useExportImport } from '@veltix/core';
 
function ExportImportComponent() {
  const {
    exportDashboard,
    importDashboard,
    exportComponent,
    importComponent
  } = useExportImport();
 
  // Export dashboard
  const exportAsJSON = async () => {
    const json = await exportDashboard(dashboard, {
      format: 'json',
      includeData: true,
      includeConfig: true
    });
    
    // Download file
    const blob = new Blob([json], { type: 'application/json' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'dashboard.json';
    a.click();
  };
 
  // Import dashboard
  const importFromFile = async (file) => {
    const text = await file.text();
    const dashboard = JSON.parse(text);
    await importDashboard(dashboard);
  };
 
  return (
    <div>
      <button onClick={exportAsJSON}>Export Dashboard</button>
      <input
        type="file"
        accept=".json"
        onChange={(e) => importFromFile(e.target.files[0])}
      />
    </div>
  );
}

Plugin API

Plugin Development


import { Plugin, usePlugin } from '@veltix/core';
 
// Plugin interface
interface PluginConfig {
  name: string;
  version: string;
  components?: ComponentConfig[];
  hooks?: HookConfig[];
  utils?: UtilityConfig[];
}
 
// Plugin hook
function PluginComponent() {
  const { plugins, registerPlugin, unregisterPlugin } = usePlugin();
 
  // Register plugin
  const registerCustomPlugin = () => {
    registerPlugin({
      name: 'custom-chart',
      version: '1.0.0',
      components: [
        {
          type: 'custom-chart',
          component: CustomChartComponent
        }
      ]
    });
  };
 
  return (
    <div>
      <button onClick={registerCustomPlugin}>
        Register Plugin
      </button>
      {plugins.map(plugin => (
        <div key={plugin.name}>{plugin.name}</div>
      ))}
    </div>
  );
}

Error Handling

Error Boundaries


import { ErrorBoundary } from '@veltix/core';
 
function DashboardWithErrorBoundary() {
  return (
    <ErrorBoundary
      fallback={<div>Something went wrong</div>}
      onError={(error, errorInfo) => {
        console.error('Dashboard error:', error, errorInfo);
      }}
    >
      <Dashboard />
    </ErrorBoundary>
  );
}

Error Handling Utilities


import { useErrorHandler } from '@veltix/core';
 
function ErrorHandlingComponent() {
  const { handleError, clearError, hasError } = useErrorHandler();
 
  const handleDataError = (error) => {
    handleError('data', error);
  };
 
  const handleRenderError = (error) => {
    handleError('render', error);
  };
 
  return (
    <div>
      {hasError('data') && <div>Data error occurred</div>}
      {hasError('render') && <div>Render error occurred</div>}
      <button onClick={() => clearError('data')}>
        Clear Data Error
      </button>
    </div>
  );
}

TypeScript Support

Type Definitions


// Core types
export interface Dashboard {
  id: string;
  title: string;
  layout: LayoutConfig;
  components: Component[];
  theme: ThemeConfig;
  dataSources: DataSource[];
}
 
export interface Component {
  id: string;
  type: string;
  position: Position;
  size: Size;
  data: any;
  config: any;
  style: CSSProperties;
}
 
export interface DataSource {
  id: string;
  type: DataSourceType;
  config: any;
  refreshInterval?: number;
  transforms?: Transform[];
}
 
// Chart types
export interface ChartConfig {
  data: any[];
  xField: string;
  yField: string;
  color?: string | string[];
  height?: number;
  width?: number;
  animation?: boolean;
  grid?: boolean;
  legend?: boolean;
  tooltip?: boolean;
}
 
// Theme types
export interface Theme {
  name: string;
  colors: ColorPalette;
  typography: TypographyConfig;
  spacing: SpacingConfig;
  borderRadius: BorderRadiusConfig;
  shadows: ShadowConfig;
}

Best Practices

1. API Usage

Use TypeScript for better type safety
Implement proper error handling
Use hooks for state management
Follow React best practices

2. Performance

Memoize expensive calculations
Use lazy loading for large components
Implement proper cleanup
Monitor API performance

3. Security

Validate all inputs
Sanitize data before rendering
Use HTTPS for external APIs
Implement proper authentication

4. Testing

Write unit tests for API functions
Test error scenarios
Mock external dependencies
Use integration tests for complex flows