Types & Interfaces

import type {
  IMutField,
  IChart,
  DraggableFieldState,
  IVisualConfigNew,
  IVisualLayout,
  IFilterRule,
  IComputationFunction,
  IThemeKey,
  IDarkMode,
  IUIThemeConfig,
  IChannelScales,
} from '@kanaries/graphic-walker';

type ISemanticType = 'quantitative' | 'nominal' | 'ordinal' | 'temporal';

type IAnalyticType = 'dimension' | 'measure';

interface IMutField {
  fid: string;                          // Field ID — must match a key in your data objects
  name?: string;                        // Display name shown in the UI
  semanticType: ISemanticType;          // Data type classification
  analyticType: IAnalyticType;          // Analysis role
  basename?: string;                    // Base name for derived fields
  disable?: boolean;                    // Hide this field from the UI
  path?: string[];                      // Path for nested data
  offset?: number;                      // Timezone offset for temporal fields
}

interface IViewField extends IField {
  sort?: 'none' | 'ascending' | 'descending';
}

interface IFilterField extends IViewField {
  rule: IFilterRule | null;
  enableAgg?: boolean;
}

interface IChart {
  visId: string;                        // Unique identifier for this chart
  name?: string;                        // Display name
  encodings: DraggableFieldState;       // Field-to-channel mappings
  config: IVisualConfigNew;             // Visualization config
  layout: IVisualLayout;                // Layout config
}

interface DraggableFieldState {
  dimensions: IViewField[];             // Available dimension fields
  measures: IViewField[];               // Available measure fields
  rows: IViewField[];                   // Y-axis encoding
  columns: IViewField[];                // X-axis encoding
  color: IViewField[];                  // Color encoding
  opacity: IViewField[];                // Opacity encoding
  size: IViewField[];                   // Size encoding
  shape: IViewField[];                  // Shape encoding
  theta: IViewField[];                  // Angle encoding (for pie/donut charts)
  radius: IViewField[];                 // Radius encoding
  longitude: IViewField[];              // Longitude for maps
  latitude: IViewField[];               // Latitude for maps
  geoId: IViewField[];                  // Geographic ID for choropleth
  details: IViewField[];                // Detail level (no visual encoding)
  filters: IFilterField[];              // Active filters
  text: IViewField[];                   // Text labels
}

interface IVisualConfigNew {
  defaultAggregated: boolean;           // Whether to aggregate measures by default
  geoms: string[];                      // Geometry types: 'bar', 'line', 'area', 'point', 'circle', 'tick', 'rect', 'arc', 'boxplot', 'table', 'poi', 'choropleth'
  coordSystem?: 'generic' | 'geographic'; // Coordinate system
  limit: number;                        // Row limit (-1 for no limit)
  folds?: string[];                     // Fields to fold/unpivot
  timezoneDisplayOffset?: number;       // Timezone offset for display
}

interface IVisualLayout {
  showTableSummary: boolean;
  format: {
    numberFormat?: string;
    timeFormat?: string;
    normalizedNumberFormat?: string;
  };
  primaryColor?: string;
  colorPalette?: string;
  scale?: IConfigScaleSet;
  resolve: {
    x?: boolean;
    y?: boolean;
    color?: boolean;
    opacity?: boolean;
    shape?: boolean;
    size?: boolean;
  };
  size: {
    mode: 'auto' | 'fixed' | 'full';
    width: number;
    height: number;
  };
  useSvg?: boolean;
  interactiveScale: boolean;
  stack: IStackMode;
  showActions: boolean;
  zeroScale: boolean;
  background?: string;
  scaleIncludeUnmatchedChoropleth?: boolean;
  showAllGeoshapeInChoropleth?: boolean;
  renderer?: 'vega-lite' | 'observable-plot';
  geoMapTileUrl?: string;
  geojson?: FeatureCollection;
  geoKey?: string;
  geoUrl?: { type: 'GeoJSON' | 'TopoJSON'; url: string };
}

type IFilterRule =
  | { type: 'range'; value: [number | null, number | null] }
  | { type: 'temporal range'; value: [number | null, number | null]; offset?: number; format?: string }
  | { type: 'one of'; value: any[] }
  | { type: 'not in'; value: any[] }
  | { type: 'regexp'; value: string; caseSensitive?: boolean };

interface IVisFilter {
  fid: string;           // Field ID to filter on
  rule: IFilterRule;      // The filter rule
}

type IComputationFunction = (payload: IDataQueryPayload) => Promise<IRow[]>;

interface IDataQueryPayload {
  workflow: IDataQueryWorkflowStep[];   // Processing pipeline
  limit?: number;
  offset?: number;
}

// Filter step — apply row-level filters
interface IFilterWorkflowStep {
  type: 'filter';
  filters: IVisFilter[];
}
 
// Transform step — compute derived fields
interface ITransformWorkflowStep {
  type: 'transform';
  transform: IFieldTransform[];
}
 
// View step — aggregate or select fields
interface IViewWorkflowStep {
  type: 'view';
  query: IViewQuery[];  // IAggQuery | IFoldQuery | IBinQuery | IRawQuery
}
 
// Sort step — order results
interface ISortWorkflowStep {
  type: 'sort';
  sort: 'ascending' | 'descending';
  by: string[];
}

type IAggregator = 'sum' | 'count' | 'max' | 'min' | 'mean' | 'median' | 'variance' | 'stdev' | 'distinctCount' | 'expr';

type IThemeKey = 'vega' | 'g2' | 'streamlit';

type IDarkMode = 'media' | 'light' | 'dark';

type IStackMode = 'none' | 'stack' | 'normalize' | 'zero' | 'center';

interface IUIThemeConfig {
  light: IColorSet;
  dark: IColorSet;
}
 
interface IColorSet {
  background: string;
  foreground: string;
  primary: string;
  'primary-foreground': string;
  muted: string;
  'muted-foreground': string;
  border: string;
  ring: string;
  // Optional overrides
  card?: string;
  'card-foreground'?: string;
  popover?: string;
  'popover-foreground'?: string;
  secondary?: string;
  'secondary-foreground'?: string;
  accent?: string;
  'accent-foreground'?: string;
  destructive?: string;
  'destructive-foreground'?: string;
  dimension?: string;
  measure?: string;
  input?: string;
}

interface IChannelScales {
  row?: IScale | ((info: IFieldInfos) => IScale);
  column?: IScale | ((info: IFieldInfos) => IScale);
  color?: IColorScale | ((info: IFieldInfos) => IColorScale);
  opacity?: IScale | ((info: IFieldInfos) => IScale);
  size?: IScale | ((info: IFieldInfos) => IScale);
  radius?: IScale | ((info: IFieldInfos) => IScale);
  theta?: IScale | ((info: IFieldInfos) => IScale);
}

type IGeographicData =
  | { type: 'GeoJSON'; data: FeatureCollection }
  | { type: 'TopoJSON'; data: Topology; objectKey?: string };

type IGeoDataItem = {
  type: 'GeoJSON' | 'TopoJSON';
  name: string;
  url: string;
};

interface IChartExportResult<T extends 'svg' | 'data-url'> {
  mode: T;
  title: string;
  nCols: number;
  nRows: number;
  charts: {
    colIndex: number;
    rowIndex: number;
    width: number;
    height: number;
    canvasWidth: number;
    canvasHeight: number;
    data: string;                       // SVG string or data URL
    canvas(): HTMLCanvasElement | SVGSVGElement | null;
  }[];
  container(): HTMLDivElement | null;
  chartType?: string;
}

interface IGWHandler {
  chartCount: number;
  chartIndex: number;
  openChart: (index: number) => void;
  renderStatus: 'computing' | 'rendering' | 'idle' | 'error';
  onRenderStatusChange: (cb: (status: IRenderStatus) => void) => () => void;
  exportChart: (mode?: 'svg' | 'data-url') => Promise<IChartExportResult>;
  exportChartList: (mode?: 'svg' | 'data-url') => AsyncGenerator<IChartListExportResult>;
}