@opendata-ai/openchart-core 2.0.0

package/src/types/__tests__/spec.test.ts

@@ -0,0 +1,387 @@
+import { describe, expect, it } from 'vitest';
+import type {
+  Annotation,
+  ChartSpec,
+  GraphSpec,
+  RangeAnnotation,
+  TableSpec,
+  TextAnnotation,
+  VizSpec,
+} from '../spec';
+import {
+  CHART_TYPES,
+  isChartSpec,
+  isGraphSpec,
+  isRangeAnnotation,
+  isRefLineAnnotation,
+  isTableSpec,
+  isTextAnnotation,
+} from '../spec';
+
+// ---------------------------------------------------------------------------
+// Test data factories
+// ---------------------------------------------------------------------------
+
+function makeChartSpec(overrides?: Partial<ChartSpec>): ChartSpec {
+  return {
+    type: 'line',
+    data: [
+      { date: '2020-01', value: 42 },
+      { date: '2020-02', value: 45 },
+    ],
+    encoding: {
+      x: { field: 'date', type: 'temporal' },
+      y: { field: 'value', type: 'quantitative' },
+    },
+    ...overrides,
+  };
+}
+
+function makeTableSpec(overrides?: Partial<TableSpec>): TableSpec {
+  return {
+    type: 'table',
+    data: [
+      { name: 'US', gdp: 21000 },
+      { name: 'China', gdp: 14700 },
+    ],
+    columns: [
+      { key: 'name', label: 'Country' },
+      { key: 'gdp', label: 'GDP (B$)', format: ',.0f' },
+    ],
+    ...overrides,
+  };
+}
+
+function makeGraphSpec(overrides?: Partial<GraphSpec>): GraphSpec {
+  return {
+    type: 'graph',
+    nodes: [
+      { id: 'a', label: 'Node A' },
+      { id: 'b', label: 'Node B' },
+    ],
+    edges: [{ source: 'a', target: 'b', weight: 1 }],
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Spec type guard tests
+// ---------------------------------------------------------------------------
+
+describe('isChartSpec', () => {
+  it('returns true for all chart types', () => {
+    const chartTypes = ['line', 'area', 'bar', 'column', 'pie', 'donut', 'dot', 'scatter'] as const;
+
+    for (const chartType of chartTypes) {
+      const spec = makeChartSpec({ type: chartType });
+      expect(isChartSpec(spec)).toBe(true);
+    }
+  });
+
+  it('returns false for table specs', () => {
+    const spec: VizSpec = makeTableSpec();
+    expect(isChartSpec(spec)).toBe(false);
+  });
+
+  it('returns false for graph specs', () => {
+    const spec: VizSpec = makeGraphSpec();
+    expect(isChartSpec(spec)).toBe(false);
+  });
+});
+
+describe('isTableSpec', () => {
+  it('returns true for table specs', () => {
+    const spec: VizSpec = makeTableSpec();
+    expect(isTableSpec(spec)).toBe(true);
+  });
+
+  it('returns false for chart specs', () => {
+    const spec: VizSpec = makeChartSpec();
+    expect(isTableSpec(spec)).toBe(false);
+  });
+
+  it('returns false for graph specs', () => {
+    const spec: VizSpec = makeGraphSpec();
+    expect(isTableSpec(spec)).toBe(false);
+  });
+});
+
+describe('isGraphSpec', () => {
+  it('returns true for graph specs', () => {
+    const spec: VizSpec = makeGraphSpec();
+    expect(isGraphSpec(spec)).toBe(true);
+  });
+
+  it('returns false for chart specs', () => {
+    const spec: VizSpec = makeChartSpec();
+    expect(isGraphSpec(spec)).toBe(false);
+  });
+
+  it('returns false for table specs', () => {
+    const spec: VizSpec = makeTableSpec();
+    expect(isGraphSpec(spec)).toBe(false);
+  });
+});
+
+describe('type guard mutual exclusivity', () => {
+  it('exactly one guard returns true for each spec type', () => {
+    const specs: VizSpec[] = [makeChartSpec(), makeTableSpec(), makeGraphSpec()];
+
+    for (const spec of specs) {
+      const guards = [isChartSpec(spec), isTableSpec(spec), isGraphSpec(spec)];
+      const trueCount = guards.filter(Boolean).length;
+      expect(trueCount).toBe(1);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// CHART_TYPES constant tests
+// ---------------------------------------------------------------------------
+
+describe('CHART_TYPES', () => {
+  it('contains all 8 chart types', () => {
+    expect(CHART_TYPES.size).toBe(8);
+  });
+
+  it('contains expected types', () => {
+    const expected = ['line', 'area', 'bar', 'column', 'pie', 'donut', 'dot', 'scatter'];
+    for (const t of expected) {
+      expect(CHART_TYPES.has(t)).toBe(true);
+    }
+  });
+
+  it('does not contain non-chart types', () => {
+    expect(CHART_TYPES.has('table')).toBe(false);
+    expect(CHART_TYPES.has('graph')).toBe(false);
+    expect(CHART_TYPES.has('map')).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Annotation type guard tests
+// ---------------------------------------------------------------------------
+
+describe('isTextAnnotation', () => {
+  it('returns true for text annotations', () => {
+    const annotation: Annotation = {
+      type: 'text',
+      x: '2020-06',
+      y: 42,
+      text: 'Peak value',
+    };
+    expect(isTextAnnotation(annotation)).toBe(true);
+  });
+
+  it('returns false for range annotations', () => {
+    const annotation: Annotation = {
+      type: 'range',
+      x1: '2020-03',
+      x2: '2020-09',
+      label: 'Recession',
+    };
+    expect(isTextAnnotation(annotation)).toBe(false);
+  });
+
+  it('returns false for refline annotations', () => {
+    const annotation: Annotation = {
+      type: 'refline',
+      y: 0,
+      label: 'Zero',
+    };
+    expect(isTextAnnotation(annotation)).toBe(false);
+  });
+});
+
+describe('isRangeAnnotation', () => {
+  it('returns true for range annotations', () => {
+    const annotation: Annotation = {
+      type: 'range',
+      x1: '2020-03',
+      x2: '2020-09',
+      fill: '#fee2e2',
+    };
+    expect(isRangeAnnotation(annotation)).toBe(true);
+  });
+
+  it('returns false for text annotations', () => {
+    const annotation: TextAnnotation = {
+      type: 'text',
+      x: 10,
+      y: 20,
+      text: 'Hello',
+    };
+    expect(isRangeAnnotation(annotation)).toBe(false);
+  });
+});
+
+describe('isRefLineAnnotation', () => {
+  it('returns true for refline annotations', () => {
+    const annotation: Annotation = {
+      type: 'refline',
+      y: 0,
+      label: 'Baseline',
+      style: 'dashed',
+    };
+    expect(isRefLineAnnotation(annotation)).toBe(true);
+  });
+
+  it('returns false for text annotations', () => {
+    const annotation: TextAnnotation = {
+      type: 'text',
+      x: 10,
+      y: 20,
+      text: 'Hello',
+    };
+    expect(isRefLineAnnotation(annotation)).toBe(false);
+  });
+
+  it('returns false for range annotations', () => {
+    const annotation: RangeAnnotation = {
+      type: 'range',
+      y1: 0,
+      y2: 100,
+    };
+    expect(isRefLineAnnotation(annotation)).toBe(false);
+  });
+});
+
+describe('annotation type guard mutual exclusivity', () => {
+  it('exactly one annotation guard returns true for each annotation type', () => {
+    const annotations: Annotation[] = [
+      { type: 'text', x: 0, y: 0, text: 'test' },
+      { type: 'range', x1: 0, x2: 10 },
+      { type: 'refline', y: 0 },
+    ];
+
+    for (const annotation of annotations) {
+      const guards = [
+        isTextAnnotation(annotation),
+        isRangeAnnotation(annotation),
+        isRefLineAnnotation(annotation),
+      ];
+      const trueCount = guards.filter(Boolean).length;
+      expect(trueCount).toBe(1);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Type-level tests (compile-time verification)
+// ---------------------------------------------------------------------------
+
+describe('type-level spec construction', () => {
+  it('allows a fully featured chart spec', () => {
+    const spec: ChartSpec = {
+      type: 'line',
+      data: [{ date: '2020-01', value: 42, series: 'US' }],
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: {
+          field: 'value',
+          type: 'quantitative',
+          axis: { label: 'GDP Growth (%)' },
+          scale: { zero: true, nice: true },
+        },
+        color: { field: 'series', type: 'nominal' },
+      },
+      chrome: {
+        title: 'GDP Growth Rate',
+        subtitle: { text: 'Quarterly, seasonally adjusted', style: { fontSize: 14 } },
+        source: 'World Bank',
+        byline: 'OpenData',
+        footer: 'Last updated: Jan 2024',
+      },
+      annotations: [
+        {
+          type: 'range',
+          x1: '2020-03',
+          x2: '2020-09',
+          label: 'COVID-19',
+          fill: '#fee2e2',
+        },
+        {
+          type: 'text',
+          x: '2021-06',
+          y: 45,
+          text: 'Recovery begins',
+        },
+        {
+          type: 'refline',
+          y: 0,
+          label: 'Zero growth',
+          style: 'dashed',
+        },
+      ],
+      responsive: true,
+      theme: {
+        colors: { categorical: ['#2563eb', '#dc2626'] },
+        fonts: { family: 'Inter' },
+      },
+      darkMode: 'auto',
+    };
+
+    // If this compiles and type-checks, the types are correct.
+    expect(spec.type).toBe('line');
+    expect(spec.data).toHaveLength(1);
+    expect(spec.encoding.x?.field).toBe('date');
+    expect(spec.annotations).toHaveLength(3);
+  });
+
+  it('allows a table spec with column configs', () => {
+    const spec: TableSpec = {
+      type: 'table',
+      data: [{ country: 'US', gdp: 21000, trend: [20000, 20500, 21000] }],
+      columns: [
+        { key: 'country', label: 'Country', sortable: true },
+        { key: 'gdp', label: 'GDP (B$)', format: ',.0f', align: 'right' },
+        {
+          key: 'trend',
+          label: 'Trend',
+          sparkline: { type: 'line', valuesField: 'trend', color: '#2563eb' },
+        },
+      ],
+      chrome: { title: 'GDP by Country' },
+      search: true,
+      pagination: { pageSize: 25 },
+      stickyFirstColumn: true,
+      compact: false,
+      darkMode: 'off',
+    };
+
+    expect(spec.type).toBe('table');
+    expect(spec.columns).toHaveLength(3);
+    expect(spec.search).toBe(true);
+  });
+
+  it('allows a graph spec with encoding and layout', () => {
+    const spec: GraphSpec = {
+      type: 'graph',
+      nodes: [
+        { id: 'a', name: 'Alice', dept: 'Engineering' },
+        { id: 'b', name: 'Bob', dept: 'Design' },
+      ],
+      edges: [{ source: 'a', target: 'b', weight: 5, type: 'collaboration' }],
+      encoding: {
+        nodeColor: { field: 'dept', type: 'nominal' },
+        nodeLabel: { field: 'name' },
+        edgeWidth: { field: 'weight', type: 'quantitative' },
+      },
+      layout: {
+        type: 'force',
+        clustering: { field: 'dept' },
+        chargeStrength: -100,
+        linkDistance: 50,
+      },
+      chrome: {
+        title: 'Team Collaboration Network',
+        source: 'HR Data',
+      },
+      darkMode: 'auto',
+    };
+
+    expect(spec.type).toBe('graph');
+    expect(spec.nodes).toHaveLength(2);
+    expect(spec.edges).toHaveLength(1);
+  });
+});

package/src/types/encoding.ts

@@ -0,0 +1,144 @@
+/**
+ * Per-chart-type encoding validation rules.
+ *
+ * Defines which encoding channels are required vs optional for each chart type.
+ * The engine compiler uses these rules to validate specs at runtime (TypeScript
+ * catches compile-time errors; these catch runtime JSON from Claude or APIs).
+ */
+
+import type { ChartType, FieldType } from './spec';
+
+// ---------------------------------------------------------------------------
+// Encoding rule types
+// ---------------------------------------------------------------------------
+
+/** Constraint on what field types are valid for an encoding channel. */
+export interface ChannelRule {
+  /** Whether this channel is required for the chart type. */
+  required: boolean;
+  /** Allowed field types. If empty, any field type is accepted. */
+  allowedTypes: FieldType[];
+}
+
+/** Encoding rules for a single chart type: which channels are required/optional. */
+export interface EncodingRule {
+  x: ChannelRule;
+  y: ChannelRule;
+  color: ChannelRule;
+  size: ChannelRule;
+  detail: ChannelRule;
+}
+
+// ---------------------------------------------------------------------------
+// Chart encoding rules
+// ---------------------------------------------------------------------------
+
+/** Helper to create a required channel rule. */
+function required(...types: FieldType[]): ChannelRule {
+  return { required: true, allowedTypes: types };
+}
+
+/** Helper to create an optional channel rule. */
+function optional(...types: FieldType[]): ChannelRule {
+  return { required: false, allowedTypes: types };
+}
+
+/**
+ * Encoding rules per chart type.
+ *
+ * Defines which channels are required and what field types they accept.
+ * The compiler uses this map to validate user specs at runtime.
+ *
+ * Key design decisions:
+ * - line/area: x is temporal/ordinal (the axis), y is quantitative (the value)
+ * - bar: horizontal bars, so y is the category axis, x is the value
+ * - column: vertical columns, so x is the category axis, y is the value
+ * - pie/donut: no x axis; y is the value (quantitative), color is the category
+ * - dot: y is the category, x is quantitative
+ * - scatter: both axes are quantitative
+ */
+export const CHART_ENCODING_RULES: Record<ChartType, EncodingRule> = {
+  line: {
+    x: required('temporal', 'ordinal'),
+    y: required('quantitative'),
+    color: optional('nominal', 'ordinal'),
+    size: optional('quantitative'),
+    detail: optional('nominal'),
+  },
+  area: {
+    x: required('temporal', 'ordinal'),
+    y: required('quantitative'),
+    color: optional('nominal', 'ordinal'),
+    size: optional('quantitative'),
+    detail: optional('nominal'),
+  },
+  bar: {
+    x: required('quantitative'),
+    y: required('nominal', 'ordinal'),
+    color: optional('nominal', 'ordinal', 'quantitative'),
+    size: optional('quantitative'),
+    detail: optional('nominal'),
+  },
+  column: {
+    x: required('nominal', 'ordinal', 'temporal'),
+    y: required('quantitative'),
+    color: optional('nominal', 'ordinal', 'quantitative'),
+    size: optional('quantitative'),
+    detail: optional('nominal'),
+  },
+  pie: {
+    x: optional(),
+    y: required('quantitative'),
+    color: required('nominal', 'ordinal'),
+    size: optional('quantitative'),
+    detail: optional('nominal'),
+  },
+  donut: {
+    x: optional(),
+    y: required('quantitative'),
+    color: required('nominal', 'ordinal'),
+    size: optional('quantitative'),
+    detail: optional('nominal'),
+  },
+  dot: {
+    x: required('quantitative'),
+    y: required('nominal', 'ordinal'),
+    color: optional('nominal', 'ordinal'),
+    size: optional('quantitative'),
+    detail: optional('nominal'),
+  },
+  scatter: {
+    x: required('quantitative'),
+    y: required('quantitative'),
+    color: optional('nominal', 'ordinal'),
+    size: optional('quantitative'),
+    detail: optional('nominal'),
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Graph encoding rules
+// ---------------------------------------------------------------------------
+
+/** Encoding rule for a single graph visual channel. */
+export interface GraphChannelRule {
+  /** Whether this channel is required. */
+  required: boolean;
+  /** Allowed field types. Empty means any type. */
+  allowedTypes: FieldType[];
+}
+
+/**
+ * Encoding rules for graph visualizations.
+ *
+ * All graph encoding channels are optional since a graph can be rendered
+ * with just nodes and edges (uniform appearance). Encoding channels add
+ * visual differentiation based on data fields.
+ */
+export const GRAPH_ENCODING_RULES: Record<string, GraphChannelRule> = {
+  nodeColor: { required: false, allowedTypes: ['nominal', 'ordinal'] },
+  nodeSize: { required: false, allowedTypes: ['quantitative'] },
+  edgeColor: { required: false, allowedTypes: ['nominal', 'ordinal'] },
+  edgeWidth: { required: false, allowedTypes: ['quantitative'] },
+  nodeLabel: { required: false, allowedTypes: [] },
+};

package/src/types/events.ts

@@ -0,0 +1,96 @@
+/**
+ * Chart interaction event types.
+ *
+ * These types define the callback signatures for user interactions with
+ * chart elements: clicking marks, hovering, legend toggles, and annotation clicks.
+ *
+ * Event handlers are optional and passed through MountOptions (vanilla) or
+ * ChartProps (React). The vanilla adapter wires DOM event listeners to
+ * mark elements and constructs these typed events from the raw browser events.
+ */
+
+import type {
+  Annotation,
+  AnnotationOffset,
+  DataRow,
+  RangeAnnotation,
+  RefLineAnnotation,
+  TextAnnotation,
+} from './spec';
+
+// ---------------------------------------------------------------------------
+// Chrome key identifiers
+// ---------------------------------------------------------------------------
+
+/** Identifies a specific chrome text element (title, subtitle, source, byline, footer). */
+export type ChromeKey = 'title' | 'subtitle' | 'source' | 'byline' | 'footer';
+
+// ---------------------------------------------------------------------------
+// Element edit events
+// ---------------------------------------------------------------------------
+
+/**
+ * Discriminated union of all element edit events.
+ * Fired by the `onEdit` callback when any editable chart element is repositioned.
+ */
+export type ElementEdit =
+  | { type: 'annotation'; annotation: TextAnnotation; offset: AnnotationOffset }
+  | {
+      type: 'annotation-connector';
+      annotation: TextAnnotation;
+      endpoint: 'from' | 'to';
+      offset: AnnotationOffset;
+    }
+  | { type: 'range-label'; annotation: RangeAnnotation; labelOffset: AnnotationOffset }
+  | { type: 'refline-label'; annotation: RefLineAnnotation; labelOffset: AnnotationOffset }
+  | { type: 'chrome'; key: ChromeKey; text: string; offset: AnnotationOffset }
+  | { type: 'series-label'; series: string; offset: AnnotationOffset }
+  | { type: 'legend'; offset: AnnotationOffset };
+
+// ---------------------------------------------------------------------------
+// Mark events
+// ---------------------------------------------------------------------------
+
+/**
+ * Event fired when a user interacts with a data mark (bar, point, line segment, etc.).
+ *
+ * Contains the underlying data row, the series it belongs to (if multi-series),
+ * the position within the chart container, and the raw browser MouseEvent.
+ */
+export interface MarkEvent {
+  /** The data row associated with the mark that was interacted with. */
+  datum: DataRow;
+  /** Series identifier, if the chart has multiple series (e.g. multi-line). */
+  series?: string;
+  /** Position of the interaction relative to the chart container. */
+  position: { x: number; y: number };
+  /** The raw browser MouseEvent. */
+  event: MouseEvent;
+}
+
+// ---------------------------------------------------------------------------
+// Chart event handler interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Event handler callbacks for chart interactions.
+ *
+ * All handlers are optional. Pass these through MountOptions (vanilla adapter)
+ * or ChartProps (React component) to receive interaction callbacks.
+ */
+export interface ChartEventHandlers {
+  /** Called when a data mark is clicked. */
+  onMarkClick?: (event: MarkEvent) => void;
+  /** Called when the mouse enters a data mark. */
+  onMarkHover?: (event: MarkEvent) => void;
+  /** Called when the mouse leaves a data mark. */
+  onMarkLeave?: () => void;
+  /** Called when a legend entry is toggled (clicked to show/hide a series). */
+  onLegendToggle?: (series: string, visible: boolean) => void;
+  /** Called when an annotation element is clicked. */
+  onAnnotationClick?: (annotation: Annotation, event: MouseEvent) => void;
+  /** Called when a text annotation label is dragged to a new position. */
+  onAnnotationEdit?: (annotation: TextAnnotation, updatedOffset: AnnotationOffset) => void;
+  /** Unified edit callback. Fires for any editable chart element (annotations, chrome, legend, series labels). */
+  onEdit?: (edit: ElementEdit) => void;
+}