Skip to content
GRAPHIC WALKER
API 참조
타입 및 인터페이스

타입 및 인터페이스

이 페이지에서는 @kanaries/graphic-walker에서 내보내는 핵심 TypeScript 타입을 문서화합니다. 타입 안전한 사용을 위해 import하세요:

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

필드 타입

ISemanticType

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

필드에 포함된 데이터의 특성을 설명합니다.

값설명예시
'quantitative'연속적인 숫자 값매출, 온도, 개수
'nominal'순서 없는 카테고리제품명, 국가
'ordinal'순서 있는 카테고리평점 수준, 학력
'temporal'날짜/시간 값주문일, 타임스탬프

IAnalyticType

type IAnalyticType = 'dimension' | 'measure';

필드가 집계에서 어떻게 사용되는지 결정합니다.

값설명
'dimension'그룹화에 사용 (GROUP BY)
'measure'집계에 사용 (SUM, AVG 등)

IMutField

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
}

IViewField

정렬 기능이 추가된 IField 확장:

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

IFilterField

필터 규칙이 추가된 IViewField 확장:

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

차트 사양

IChart

단일 차트의 완전한 사양:

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
}

DraggableFieldState

필드를 시각적 인코딩 채널에 매핑합니다:

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
}

IVisualConfigNew

시각화 동작을 제어합니다:

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
}

IVisualLayout

차트 레이아웃 및 외관을 제어합니다:

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 };
}

필터 타입

IFilterRule

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 };
타입설명예시
'range'숫자 범위 필터{ type: 'range', value: [0, 100] }
'temporal range'날짜 범위 필터{ type: 'temporal range', value: [startTs, endTs] }
'one of'일치하는 값 포함{ type: 'one of', value: ['A', 'B'] }
'not in'일치하는 값 제외{ type: 'not in', value: ['C'] }
'regexp'정규식 패턴 매칭{ type: 'regexp', value: '^test' }

IVisFilter

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

연산 타입

IComputationFunction

서버 측 연산의 시그니처:

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

IDataQueryPayload

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[];
}

집계 타입

IAggregator

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

외관 타입

IThemeKey

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

IDarkMode

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

IStackMode

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

IUIThemeConfig

라이트 및 다크 모드의 커스텀 UI 색상:

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;
}

IChannelScales

시각적 채널의 커스텀 스케일:

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);
}

지리적 타입

IGeographicData

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

IGeoDataItem

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

차트 내보내기 타입

IChartExportResult

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;
}

IGWHandler

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>;
}
TableWalkerVanilla JS 임베딩