@opendata-ai/openchart-core 3.0.0 → 6.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-core",
-  "version": "3.0.0",
+  "version": "6.1.0",
   "description": "Types, theme, colors, accessibility, and utilities for openchart",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",

package/src/accessibility/__tests__/alt-text.test.ts

@@ -3,7 +3,7 @@ import type { ChartSpec } from '../../types/spec';
 import { generateAltText, generateDataTable } from '../alt-text';
 
 const lineSpec: ChartSpec = {
-  type: 'line',
+  mark: 'line',
   data: [
     { date: '2020-01-01', value: 10, country: 'US' },
     { date: '2021-01-01', value: 20, country: 'US' },
@@ -19,7 +19,7 @@ const lineSpec: ChartSpec = {
 };
 
 const barSpec: ChartSpec = {
-  type: 'bar',
+  mark: 'bar',
   data: [
     { category: 'A', value: 10 },
     { category: 'B', value: 20 },
@@ -86,7 +86,7 @@ describe('generateDataTable', () => {
 
   it('only includes encoded fields', () => {
     const spec: ChartSpec = {
-      type: 'bar',
+      mark: 'bar',
       data: [{ category: 'A', value: 10, extra: 'ignored' }],
       encoding: {
         x: { field: 'category', type: 'nominal' },
@@ -100,7 +100,7 @@ describe('generateDataTable', () => {
 
   it('returns empty for spec with no encoding fields', () => {
     const spec: ChartSpec = {
-      type: 'pie',
+      mark: 'arc',
       data: [{ value: 10 }],
       encoding: {},
     };

package/src/accessibility/alt-text.ts

@@ -6,23 +6,12 @@
  */
 
 import type { ChartSpec, DataRow } from '../types/spec';
+import { MARK_DISPLAY_NAMES, resolveMarkDef, resolveMarkType } from '../types/spec';
 
 // ---------------------------------------------------------------------------
 // Alt text generation
 // ---------------------------------------------------------------------------
 
-/** Friendly display names for chart types. */
-const CHART_TYPE_NAMES: Record<string, string> = {
-  line: 'Line chart',
-  area: 'Area chart',
-  bar: 'Bar chart',
-  column: 'Column chart',
-  pie: 'Pie chart',
-  donut: 'Donut chart',
-  dot: 'Dot plot',
-  scatter: 'Scatter plot',
-};
-
 /**
  * Generate alt text describing a chart's content.
  *
@@ -33,7 +22,15 @@ const CHART_TYPE_NAMES: Record<string, string> = {
  * @param data - The data array.
  */
 export function generateAltText(spec: ChartSpec, data: DataRow[]): string {
-  const chartName = CHART_TYPE_NAMES[spec.type] ?? `${spec.type} chart`;
+  const markType = resolveMarkType(spec.mark);
+  const markDef = resolveMarkDef(spec.mark);
+  let chartName = MARK_DISPLAY_NAMES[markType] ?? `${markType} chart`;
+
+  // Special case: donut detection
+  if (markType === 'arc' && markDef.innerRadius && markDef.innerRadius > 0) {
+    chartName = 'Donut chart';
+  }
+
   const parts: string[] = [chartName];
 
   // Add title context if present
@@ -68,7 +65,7 @@ export function generateAltText(spec: ChartSpec, data: DataRow[]): string {
   }
 
   // Describe series if color encoding is present
-  if (spec.encoding.color && data.length > 0) {
+  if (spec.encoding.color && 'field' in spec.encoding.color && data.length > 0) {
     const colorField = spec.encoding.color.field;
     const uniqueSeries = [...new Set(data.map((d) => String(d[colorField])).filter(Boolean))];
     if (uniqueSeries.length > 0) {
@@ -102,8 +99,8 @@ export function generateDataTable(spec: ChartSpec, data: DataRow[]): unknown[][]
 
   if (encoding.x) fields.push(encoding.x.field);
   if (encoding.y) fields.push(encoding.y.field);
-  if (encoding.color) fields.push(encoding.color.field);
-  if (encoding.size) fields.push(encoding.size.field);
+  if (encoding.color && 'field' in encoding.color) fields.push(encoding.color.field);
+  if (encoding.size && 'field' in encoding.size) fields.push(encoding.size.field);
 
   // Deduplicate
   const uniqueFields = [...new Set(fields)];

package/src/helpers/__tests__/spec-builders.test.ts

@@ -102,7 +102,7 @@ describe('lineChart', () => {
   it('creates a line chart spec with string field names', () => {
     const spec = lineChart(timeSeriesData, 'date', 'value');
 
-    expect(spec.type).toBe('line');
+    expect(spec.mark).toBe('line');
     expect(spec.data).toBe(timeSeriesData);
     expect(spec.encoding.x).toEqual({ field: 'date', type: 'temporal' });
     expect(spec.encoding.y).toEqual({ field: 'value', type: 'quantitative' });
@@ -163,7 +163,7 @@ describe('barChart', () => {
   it('maps category to y-axis and value to x-axis', () => {
     const spec = barChart(categoricalData, 'name', 'count');
 
-    expect(spec.type).toBe('bar');
+    expect(spec.mark).toBe('bar');
     // Bar chart convention: category on y, value on x
     expect(spec.encoding.y).toEqual({ field: 'name', type: 'nominal' });
     expect(spec.encoding.x).toEqual({ field: 'count', type: 'quantitative' });
@@ -190,7 +190,9 @@ describe('columnChart', () => {
   it('creates a column chart spec with x and y', () => {
     const spec = columnChart(categoricalData, 'name', 'count');
 
-    expect(spec.type).toBe('column');
+    // columnChart now produces mark: 'bar' (vertical orientation inferred from encoding)
+    expect(typeof spec.mark).toBe('object');
+    expect((spec.mark as Record<string, unknown>).type).toBe('bar');
     expect(spec.encoding.x).toEqual({ field: 'name', type: 'nominal' });
     expect(spec.encoding.y).toEqual({ field: 'count', type: 'quantitative' });
   });
@@ -204,8 +206,8 @@ describe('pieChart', () => {
   it('maps category to color channel and value to y', () => {
     const spec = pieChart(categoricalData, 'name', 'count');
 
-    expect(spec.type).toBe('pie');
-    // Pie chart convention: value on y, category on color, no x
+    expect(spec.mark).toBe('arc');
+    // Arc (pie) convention: value on y, category on color, no x
     expect(spec.encoding.y).toEqual({ field: 'count', type: 'quantitative' });
     expect(spec.encoding.color).toEqual({ field: 'name', type: 'nominal' });
     expect(spec.encoding.x).toBeUndefined();
@@ -226,7 +228,7 @@ describe('scatterChart', () => {
   it('creates a scatter chart with both axes quantitative', () => {
     const spec = scatterChart(numericData, 'x', 'y');
 
-    expect(spec.type).toBe('scatter');
+    expect(spec.mark).toBe('point');
     expect(spec.encoding.x).toEqual({ field: 'x', type: 'quantitative' });
     expect(spec.encoding.y).toEqual({ field: 'y', type: 'quantitative' });
   });

package/src/helpers/spec-builders.ts

@@ -12,13 +12,14 @@
 import type {
   Annotation,
   ChartSpec,
-  ChartType,
   Chrome,
   DarkMode,
   DataRow,
   Encoding,
   EncodingChannel,
   FieldType,
+  MarkDef,
+  MarkType,
   TableSpec,
   ThemeConfig,
 } from '../types/spec';
@@ -156,12 +157,12 @@ function buildEncoding(
 
 /** Build a ChartSpec from the resolved pieces. */
 function buildChartSpec(
-  type: ChartType,
+  mark: MarkType | MarkDef,
   data: DataRow[],
   encoding: Encoding,
   options?: ChartBuilderOptions,
 ): ChartSpec {
-  const spec: ChartSpec = { type, data, encoding };
+  const spec: ChartSpec = { mark, data, encoding };
   if (options?.chrome) spec.chrome = options.chrome;
   if (options?.annotations) spec.annotations = options.annotations;
   if (options?.responsive !== undefined) spec.responsive = options.responsive;
@@ -236,7 +237,7 @@ export function columnChart(
   const xChannel = resolveField(x, data);
   const yChannel = resolveField(y, data);
   const encoding = buildEncoding({ x: xChannel, y: yChannel }, options, data);
-  return buildChartSpec('column', data, encoding, options);
+  return buildChartSpec({ type: 'bar' } as MarkDef, data, encoding, options);
 }
 
 /**
@@ -269,7 +270,7 @@ export function pieChart(
     encoding.size = resolveField(options.size, data);
   }
 
-  return buildChartSpec('pie', data, encoding, options);
+  return buildChartSpec('arc', data, encoding, options);
 }
 
 /**
@@ -321,7 +322,7 @@ export function donutChart(
     encoding.size = resolveField(options.size, data);
   }
 
-  return buildChartSpec('donut', data, encoding, options);
+  return buildChartSpec({ type: 'arc', innerRadius: 40 } as MarkDef, data, encoding, options);
 }
 
 /**
@@ -341,7 +342,7 @@ export function dotChart(
   const xChannel = resolveField(x, data);
   const yChannel = resolveField(y, data);
   const encoding = buildEncoding({ x: xChannel, y: yChannel }, options, data);
-  return buildChartSpec('dot', data, encoding, options);
+  return buildChartSpec('circle', data, encoding, options);
 }
 
 /**
@@ -361,7 +362,7 @@ export function scatterChart(
   const xChannel = resolveField(x, data);
   const yChannel = resolveField(y, data);
   const encoding = buildEncoding({ x: xChannel, y: yChannel }, options, data);
-  return buildChartSpec('scatter', data, encoding, options);
+  return buildChartSpec('point', data, encoding, options);
 }
 
 /**

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

@@ -0,0 +1,267 @@
+import { describe, expect, it } from 'vitest';
+import { MARK_ENCODING_RULES } from '../encoding';
+import type { MarkType } from '../spec';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function getChannelNames(markType: MarkType): string[] {
+  return Object.keys(MARK_ENCODING_RULES[markType]);
+}
+
+function getRequiredChannels(markType: MarkType): string[] {
+  return Object.entries(MARK_ENCODING_RULES[markType])
+    .filter(([, rule]) => rule.required)
+    .map(([ch]) => ch);
+}
+
+function getOptionalChannels(markType: MarkType): string[] {
+  return Object.entries(MARK_ENCODING_RULES[markType])
+    .filter(([, rule]) => !rule.required)
+    .map(([ch]) => ch);
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('MARK_ENCODING_RULES', () => {
+  it('has entries for all 10 mark types', () => {
+    const expectedTypes: MarkType[] = [
+      'bar',
+      'line',
+      'area',
+      'point',
+      'circle',
+      'arc',
+      'text',
+      'rule',
+      'tick',
+      'rect',
+    ];
+    for (const type of expectedTypes) {
+      expect(MARK_ENCODING_RULES[type]).toBeDefined();
+    }
+  });
+
+  it('every mark type has x, y, color, size, and detail channels', () => {
+    const baseChannels = ['x', 'y', 'color', 'size', 'detail'];
+    for (const [_markType, rules] of Object.entries(MARK_ENCODING_RULES)) {
+      for (const ch of baseChannels) {
+        expect(rules[ch as keyof typeof rules]).toBeDefined();
+      }
+    }
+  });
+});
+
+describe('bar encoding rules', () => {
+  it('requires x and y', () => {
+    expect(getRequiredChannels('bar')).toContain('x');
+    expect(getRequiredChannels('bar')).toContain('y');
+  });
+
+  it('supports x2 and y2 as optional', () => {
+    expect(getOptionalChannels('bar')).toContain('x2');
+    expect(getOptionalChannels('bar')).toContain('y2');
+  });
+
+  it('supports opacity, tooltip, href, order, detail', () => {
+    const optionals = getOptionalChannels('bar');
+    expect(optionals).toContain('opacity');
+    expect(optionals).toContain('tooltip');
+    expect(optionals).toContain('href');
+    expect(optionals).toContain('order');
+    expect(optionals).toContain('detail');
+  });
+
+  it('does not support shape, strokeDash, text, theta, radius', () => {
+    const channels = getChannelNames('bar');
+    expect(channels).not.toContain('shape');
+    expect(channels).not.toContain('strokeDash');
+    expect(channels).not.toContain('text');
+    expect(channels).not.toContain('theta');
+    expect(channels).not.toContain('radius');
+  });
+});
+
+describe('line encoding rules', () => {
+  it('requires x (temporal/ordinal) and y (quantitative)', () => {
+    const rules = MARK_ENCODING_RULES.line;
+    expect(rules.x.required).toBe(true);
+    expect(rules.x.allowedTypes).toContain('temporal');
+    expect(rules.y.required).toBe(true);
+    expect(rules.y.allowedTypes).toContain('quantitative');
+  });
+
+  it('supports strokeDash as optional', () => {
+    expect(getOptionalChannels('line')).toContain('strokeDash');
+  });
+
+  it('does not support shape, text, theta, radius, x2, y2', () => {
+    const channels = getChannelNames('line');
+    expect(channels).not.toContain('shape');
+    expect(channels).not.toContain('text');
+    expect(channels).not.toContain('theta');
+    expect(channels).not.toContain('radius');
+    expect(channels).not.toContain('x2');
+    expect(channels).not.toContain('y2');
+  });
+});
+
+describe('point encoding rules', () => {
+  it('supports shape as optional', () => {
+    expect(getOptionalChannels('point')).toContain('shape');
+  });
+
+  it('supports size as optional quantitative', () => {
+    const rules = MARK_ENCODING_RULES.point;
+    expect(rules.size.required).toBe(false);
+    expect(rules.size.allowedTypes).toContain('quantitative');
+  });
+});
+
+describe('arc encoding rules', () => {
+  it('requires y (quantitative) and color (nominal/ordinal)', () => {
+    const rules = MARK_ENCODING_RULES.arc;
+    expect(rules.y.required).toBe(true);
+    expect(rules.y.allowedTypes).toContain('quantitative');
+    expect(rules.color.required).toBe(true);
+    expect(rules.color.allowedTypes).toContain('nominal');
+  });
+
+  it('supports theta and radius as optional', () => {
+    const optionals = getOptionalChannels('arc');
+    expect(optionals).toContain('theta');
+    expect(optionals).toContain('radius');
+  });
+});
+
+describe('text encoding rules', () => {
+  it('requires text channel', () => {
+    const rules = MARK_ENCODING_RULES.text;
+    expect(rules.text!.required).toBe(true);
+  });
+
+  it('has optional x and y', () => {
+    const rules = MARK_ENCODING_RULES.text;
+    expect(rules.x.required).toBe(false);
+    expect(rules.y.required).toBe(false);
+  });
+
+  it('supports size as optional quantitative', () => {
+    const rules = MARK_ENCODING_RULES.text;
+    expect(rules.size.required).toBe(false);
+    expect(rules.size.allowedTypes).toContain('quantitative');
+  });
+});
+
+describe('rule encoding rules', () => {
+  it('has optional x, y, x2, y2', () => {
+    const rules = MARK_ENCODING_RULES.rule;
+    expect(rules.x.required).toBe(false);
+    expect(rules.y.required).toBe(false);
+    expect(rules.x2!.required).toBe(false);
+    expect(rules.y2!.required).toBe(false);
+  });
+
+  it('supports strokeDash as optional', () => {
+    expect(getOptionalChannels('rule')).toContain('strokeDash');
+  });
+});
+
+describe('tick encoding rules', () => {
+  it('requires x and y', () => {
+    expect(getRequiredChannels('tick')).toContain('x');
+    expect(getRequiredChannels('tick')).toContain('y');
+  });
+
+  it('supports opacity, tooltip, href, detail', () => {
+    const optionals = getOptionalChannels('tick');
+    expect(optionals).toContain('opacity');
+    expect(optionals).toContain('tooltip');
+    expect(optionals).toContain('href');
+    expect(optionals).toContain('detail');
+  });
+});
+
+describe('rect encoding rules', () => {
+  it('requires x and y', () => {
+    expect(getRequiredChannels('rect')).toContain('x');
+    expect(getRequiredChannels('rect')).toContain('y');
+  });
+
+  it('supports x2, y2, opacity, order', () => {
+    const optionals = getOptionalChannels('rect');
+    expect(optionals).toContain('x2');
+    expect(optionals).toContain('y2');
+    expect(optionals).toContain('opacity');
+    expect(optionals).toContain('order');
+  });
+});
+
+describe('common channels across marks', () => {
+  it('tooltip is optional on all mark types', () => {
+    const allTypes: MarkType[] = [
+      'bar',
+      'line',
+      'area',
+      'point',
+      'circle',
+      'arc',
+      'text',
+      'rule',
+      'tick',
+      'rect',
+    ];
+    for (const type of allTypes) {
+      const rules = MARK_ENCODING_RULES[type];
+      if (rules.tooltip) {
+        expect(rules.tooltip.required).toBe(false);
+      }
+    }
+  });
+
+  it('href is optional on all mark types that have it', () => {
+    const allTypes: MarkType[] = [
+      'bar',
+      'line',
+      'area',
+      'point',
+      'circle',
+      'arc',
+      'text',
+      'rule',
+      'tick',
+      'rect',
+    ];
+    for (const type of allTypes) {
+      const rules = MARK_ENCODING_RULES[type];
+      if (rules.href) {
+        expect(rules.href.required).toBe(false);
+      }
+    }
+  });
+
+  it('opacity is optional quantitative on all mark types that have it', () => {
+    const allTypes: MarkType[] = [
+      'bar',
+      'line',
+      'area',
+      'point',
+      'circle',
+      'arc',
+      'text',
+      'rule',
+      'tick',
+      'rect',
+    ];
+    for (const type of allTypes) {
+      const rules = MARK_ENCODING_RULES[type];
+      if (rules.opacity) {
+        expect(rules.opacity.required).toBe(false);
+        expect(rules.opacity.allowedTypes).toContain('quantitative');
+      }
+    }
+  });
+});

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

@@ -5,7 +5,6 @@ import type {
   GraphSpec,
   RangeAnnotation,
   TableSpec,
-  TextAnnotation,
   VizSpec,
 } from '../spec';
 import {
@@ -16,6 +15,7 @@ import {
   isRefLineAnnotation,
   isTableSpec,
   isTextAnnotation,
+  MARK_TYPES,
 } from '../spec';
 
 // ---------------------------------------------------------------------------
@@ -24,7 +24,7 @@ import {
 
 function makeChartSpec(overrides?: Partial<ChartSpec>): ChartSpec {
   return {
-    type: 'line',
+    mark: 'line',
     data: [
       { date: '2020-01', value: 42 },
       { date: '2020-02', value: 45 },
@@ -69,11 +69,22 @@ function makeGraphSpec(overrides?: Partial<GraphSpec>): GraphSpec {
 // ---------------------------------------------------------------------------
 
 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 });
+  it('returns true for all mark types', () => {
+    const markTypes = [
+      'line',
+      'area',
+      'bar',
+      'point',
+      'circle',
+      'arc',
+      'text',
+      'rule',
+      'tick',
+      'rect',
+    ] as const;
+
+    for (const markType of markTypes) {
+      const spec = makeChartSpec({ mark: markType });
       expect(isChartSpec(spec)).toBe(true);
     }
   });
@@ -136,25 +147,40 @@ describe('type guard mutual exclusivity', () => {
 });
 
 // ---------------------------------------------------------------------------
-// CHART_TYPES constant tests
+// MARK_TYPES constant tests
 // ---------------------------------------------------------------------------
 
-describe('CHART_TYPES', () => {
-  it('contains all 8 chart types', () => {
-    expect(CHART_TYPES.size).toBe(8);
+describe('MARK_TYPES', () => {
+  it('contains all 10 mark types', () => {
+    expect(MARK_TYPES.size).toBe(10);
   });
 
   it('contains expected types', () => {
-    const expected = ['line', 'area', 'bar', 'column', 'pie', 'donut', 'dot', 'scatter'];
+    const expected = [
+      'line',
+      'area',
+      'bar',
+      'point',
+      'circle',
+      'arc',
+      'text',
+      'rule',
+      'tick',
+      'rect',
+    ];
     for (const t of expected) {
-      expect(CHART_TYPES.has(t)).toBe(true);
+      expect(MARK_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);
+  it('does not contain non-mark types', () => {
+    expect(MARK_TYPES.has('table')).toBe(false);
+    expect(MARK_TYPES.has('graph')).toBe(false);
+    expect(MARK_TYPES.has('map')).toBe(false);
+  });
+
+  it('CHART_TYPES is an alias for MARK_TYPES', () => {
+    expect(CHART_TYPES).toBe(MARK_TYPES);
   });
 });
 
@@ -205,7 +231,7 @@ describe('isRangeAnnotation', () => {
   });
 
   it('returns false for text annotations', () => {
-    const annotation: TextAnnotation = {
+    const annotation: Annotation = {
       type: 'text',
       x: 10,
       y: 20,
@@ -227,7 +253,7 @@ describe('isRefLineAnnotation', () => {
   });
 
   it('returns false for text annotations', () => {
-    const annotation: TextAnnotation = {
+    const annotation: Annotation = {
       type: 'text',
       x: 10,
       y: 20,
@@ -273,14 +299,14 @@ describe('annotation type guard mutual exclusivity', () => {
 describe('type-level spec construction', () => {
   it('allows a fully featured chart spec', () => {
     const spec: ChartSpec = {
-      type: 'line',
+      mark: 'line',
       data: [{ date: '2020-01', value: 42, series: 'US' }],
       encoding: {
         x: { field: 'date', type: 'temporal' },
         y: {
           field: 'value',
           type: 'quantitative',
-          axis: { label: 'GDP Growth (%)' },
+          axis: { title: 'GDP Growth (%)' },
           scale: { zero: true, nice: true },
         },
         color: { field: 'series', type: 'nominal' },
@@ -322,12 +348,25 @@ describe('type-level spec construction', () => {
     };
 
     // If this compiles and type-checks, the types are correct.
-    expect(spec.type).toBe('line');
+    expect(spec.mark).toBe('line');
     expect(spec.data).toHaveLength(1);
     expect(spec.encoding.x?.field).toBe('date');
     expect(spec.annotations).toHaveLength(3);
   });
 
+  it('allows a chart spec with mark object', () => {
+    const spec: ChartSpec = {
+      mark: { type: 'line', interpolate: 'step', point: true },
+      data: [{ x: 1, y: 2 }],
+      encoding: {
+        x: { field: 'x', type: 'quantitative' },
+        y: { field: 'y', type: 'quantitative' },
+      },
+    };
+
+    expect(typeof spec.mark).toBe('object');
+  });
+
   it('allows a table spec with column configs', () => {
     const spec: TableSpec = {
       type: 'table',