Data Transformation

/**
 * Transforms chart props into ECharts-compatible configuration
 * Handles data processing, formatting, and visualization setup
 * @param chartProps - Chart properties including form data and query results
 * @returns Transformed props ready for chart rendering
 */
function transformProps(
  chartProps: EchartsTimeseriesChartProps
): TimeseriesChartTransformedProps;

import { transformProps } from "@superset-ui/plugin-chart-echarts";

const transformedProps = transformProps({
  formData: {
    // EchartsTimeseriesFormData configuration
    seriesType: EchartsTimeseriesSeriesType.Line,
    area: false,
    markerEnabled: true,
    // ... other configuration
  },
  queriesData: [queryResult],
  // ... other chart props
});

/**
 * Transformed props interface containing processed data and configuration
 */
interface TimeseriesChartTransformedProps extends 
  BaseTransformedProps<EchartsTimeseriesFormData>,
  ContextMenuTransformedProps,
  CrossFilterTransformedProps {
  /** Legend data for chart legend rendering */
  legendData?: OptionName[];
  /** Formatter for x-axis values */
  xValueFormatter: TimeFormatter | StringConstructor;
  /** X-axis configuration */
  xAxis: {
    label: string;
    type: AxisType;
  };
  /** Handler for series focus events */
  onFocusedSeries: (series: string | null) => void;
}

/**
 * Base transformed props interface
 */
interface BaseTransformedProps<F> {
  /** ECharts configuration object */
  echartOptions: EChartsCoreOption;
  /** Original form data configuration */
  formData: F;
  /** Chart height in pixels */
  height: number;
  /** Chart width in pixels */
  width: number;
  /** Component references for chart interaction */
  refs: Refs;
  /** Context menu handler */
  onContextMenu?: (
    clientX: number,
    clientY: number,
    filters?: ContextMenuFilters,
  ) => void;
  /** Data mask setter for cross-filtering */
  setDataMask?: SetDataMaskHook;
  /** Legend state change handler */
  onLegendStateChanged?: (state: LegendState) => void;
  /** Current filter state */
  filterState?: FilterState;
  /** Enable cross-filter emission */
  emitCrossFilters?: boolean;
  /** Column type mapping for data processing */
  coltypeMapping?: Record<string, number>;
  /** Legend scroll handler */
  onLegendScroll?: (currentIndex: number) => void;
}

/**
 * Context menu properties for chart interaction
 */
type ContextMenuTransformedProps = {
  /** Context menu click handler */
  onContextMenu?: (
    clientX: number,
    clientY: number,
    filters?: ContextMenuFilters,
  ) => void;
  /** Data mask setter for filtering */
  setDataMask?: SetDataMaskHook;
};

/**
 * Cross-filtering properties for dashboard interaction
 */
type CrossFilterTransformedProps = {
  /** Grouping columns for cross-filtering */
  groupby: QueryFormColumn[];
  /** Label mapping for display names */
  labelMap: Record<string, string[]>;
  /** Control value setter */
  setControlValue?: HandlerFunction;
  /** Data mask setter for cross-filtering */
  setDataMask: SetDataMaskHook;
  /** Currently selected values */
  selectedValues: Record<number, string>;
  /** Enable cross-filter emission */
  emitCrossFilters?: boolean;
};

/**
 * Annotation layer processing for chart overlays
 */
interface AnnotationLayer {
  annotationType: AnnotationType;
  name: string;
  show: boolean;
  value?: any;
  overrides?: Record<string, any>;
}

enum AnnotationType {
  Event = 'EVENT',
  Formula = 'FORMULA', 
  Interval = 'INTERVAL',
  Timeseries = 'TIME_SERIES',
}

/**
 * Forecast series context for identifying forecast data
 */
type ForecastSeriesContext = {
  name: string;
  type: ForecastSeriesEnum;
};

enum ForecastSeriesEnum {
  Observation = '',
  ForecastTrend = '__yhat',
  ForecastUpper = '__yhat_upper',
  ForecastLower = '__yhat_lower',
}